Skip to content

About

CodeMetropolis is a software visualisation tool. It can create a Minecraft world using the values of source code metrics and the structure of the source code. Thus explore the inner structure of the program or compare several source code elements is easier. CodeMetropolis uses city metaphor for the visualisation of code elements like classes, functions or attributes. The city metaphor is one of the best known metaphors in software visualization. In this metaphor the source code components are represented as a part of a generated city, for example classes represented as buildings or methods represented as floor.
It is a set of command line programs, connected into a single toolchain and a couple of supporting plug-ins and scripsts. The first tool is the CDF Converter Tool. This tool creates properties for each item from a graph file, for exmaple functions or methods. The second tool is the Mapping Tool, which processes the output XML file of Converter Tool, assigns metrics to objects of the metropolis and generates an ouput XML that is ready to be used by the Placing Tool. The third tool is Placing Tool. This tool creates the city layout and generates an output XML that is ready to be used by the Render Tool. The last tool is Render Tool. This tool proccesses the ouput XML file of Placing Tool and creates a virtual city in a Minecraft world.
CodeMetropolis tools use XML files to communicate with eachother. CDF Converter Tool produces an XML file from the graph file of the source code, then Mapping Tool using the previous XML file generates an ouput XML file which is the input file for the Placing Tool. Then the Placing Tool generates an output XML file for the Rendering Tool. These last two XML files use the same format defined in an XML Schema.

Installation guide

In order to use all functionality of CodeMetropolis you have to install the following dependencies.

SourceMeter could be used with the following command:

SourceMeterJava.exe -projectName=<inputProjectName> -projectBaseDir=<inputProjectDir>
-resultsDir=<ResultsDir>

Options:

  • -projectName= The name of the project. It will be the name of the directory in the results directory.

  • -projectBaseDir= The path of the directory of the source code.

  • -resultsDir= The path of the directory where the results will be stored.

After that, you can find the graph file in <ResultsDir><inputProjectName>\java\<date>. You can find more information in the documentation of SourceMeter.

CDF Converter Tool

First you have to run the CDF Converter Tool with the following command:

java -jar converter.jar -i <graph file> [-o <output.xml>] [-t <tpye>] [-p <parameter>]

Options:

  • -i: input, the path of the input graph file. Required.

  • -o: output, the path of the output XML file.

  • -t: type, the type of the conversion. In the current version it can be 'sourcemeter' or 'sonarqube'.

  • -p: parameter, a string value, for example: -p projects=project1,project2 splitDirs=true.

Output XML will be used by the Mapping Tool.

Details...

Mapping Tool

Then you have to run Mapping Tool with the following command:

java -jar mapping.jar -i <inputFile> -o <outputFile> -m <mappingFile>

Options:

  • -i <path>, --input <path>
    Path of the XML file generated by the Converter Tool. Required.

  • -o <path>, --output <path>
    Output will be generated with the given path. Default: "mappingToPlacing.xml".

  • -m <path>, --mapping <path>
    Path of the input mapping file. Required.

The mapping file contains the parameters of build up the virtual world from the source code. You could find more information about its structure and format in the detailed description of the Mapping Tool. Output XML now should be generated in output directory.

Details...

Placing Tool

Second you have to run Placing Tool with the following command:

java -jar placing.jar -i <inputFile>

  • -i <path>, --input <path>
    Path of the input XML file. This XML file is generated by Mapping Tool. Required.

  • -o <path>, --output <path> Output will be generated with the given path. Default: "placingToRendering.xml".

  • -m, --map Shows the map of the generated metropolis.

Output XML now should be generated in the given output directory.

Details...

Rendering Tool

Then you have to run Rendering Tool with following command::

java -jar rendering.jar -i <inputFile> -world <worldPath>

Options:

  • -i <path>, --input <path>
    Path of the input XML file. This XML file is generated by the Placing Tool. Required.

  • -w <path>, -world <path>
    The path of the folder where the world will be placed. Required.

Output world now should be generated in output directory. It may take a long time, depending on the size of the input.

Details...

Displaying the Generated City

You can find the generated world in the output directory. You have to copy this folder to the "saves" folder in root of Minecraft. You can usually find it at "C:\Users\<username>\AppData\Roaming\.minecraft\" directory.

After that you have to start Minecraft, choose SinglePlayer, then choose the generated world and the selected world will be displayed.

Contribution guide

This section of the documentation contains a guide for users who would like to contribute code or documentation to the CodeMetropolis project. If you would like to contribute in the project, please send your patches to review. You have to follow the these steps:

  1. Install Git LFS 1.1.0 (or newer) and Git 2.7.0 (or newer).
  2. Checkout the develop branch from this repository.
  3. Start Eclipse and set the workspace the root directory.
  4. Import the project with Existing Maven Projects and the root directory will be the same as the workspace path.
  5. Make your changes, improvements or fixes.
  6. Create a patch.
  7. Post the patch as attachment of a new issue with a description of your contribution.

After that you can run the three tool mentioned above in Eclipse. You have to set the arguments, which is in the Installation Guide section. You can set the arguments in Run Configuration, and run the tools with Run As/Java Application.

You can create a jar file with Maven with mvn package command. You have to start command line in toolchain-repository/sources directory and type the command. Then there will be a target directory in every project's directory and this target directory contain the created jar and a lib directory, which is also required to generate cities. It is recommended to copy all jar files to a common directory with the lib directory, which has to contain all lib directory content of each tool.

How to use CodeMetropolis with custom data source

CodeMetropolis converter logic has been designed to make it easy to visualize data from any source. The toolchain ships with converters for SourceMeter and SonarQube. These tools are great for presenting the structure and metrics of software projects but there might be a bunch of other use cases in which visualization could be very useful. By implementing a custom converter one can build a metropolis based on not just software entities, but any kind of data. This short tutorial will show you how to create your own converter.

Details...