Mapping Tool

This application is used to process the XML file generated by the CDF Converter Tool, assigns metrics to objects of the metropolis and generates an output XML that is ready to be used by CodeMetropolis Placing Tool. The tool is using the mapping file to link source code elements and metrics to world objects. For example, link of the LOC metric is related to the height of the building. The source tag contains the metric that will be a link to the object, the name parameter is the element of the source code and the from parameter is the metric. The target parameter is the world object, the name parameter is the name of the element in the city and the to parameter is the property of the element. If the value of the metric doesn't fit the world element, you have to use conversion.

Usage: java -jar mapping.jar -i <inputFile> -m <mappingFile> [-o <outputFile>]

Command line options:

  • -h: help, shows the usage of the command line tool.
  • -i: input, the path of the input XML file generated by the Converter Tool. Required.
  • -o: output, which will be generated to the given path. Default: "mappingToPlacing.xml".
  • -m: mapping, path of the input mapping file. Required.
  • -s: scale. Set the scale of blocks. Default: 1.0
  • -v: validate. Default: false. In case of true, the tool will validate the generated structure elements, if it's false, the invalid structure elements will be thrown.

About the mapping file

Mapping tool uses an XML file to determine the bindings from source elements to buildings of the world. Editing this file allows you to use the city metaphors the way you want. Mapping XMLs must follow a specific format.

<linking source="method" target="floor">
    <binding from="LLOC" to="height"/>
    <binding from="NII" to="width"/>
    <binding from="NOI" to="length"/>
    <binding from="McCC" to="character">
        <conversions>
            <conversion type="quantization">
                <parameter name="level0" value="glass"/>
                <parameter name="level1" value="sand"/>
                <parameter name="level2" value="planks"/>
                <parameter name="level3" value="stone"/>
                <parameter name="level4" value="obsidian"/>
            </conversion>
        </conversions>
    </binding>
</linking>

In the <linking> tag it can be set how a program element should be displayed in the world. The source must be an existing type of the input CDF, while the target specifies the building type to which the source will be linked to. The valid building types are the following: ground, garden, floor, cellar.

The bindings are used to tell the mapping component which properties of the source element to bind to which attribute of the target object. The table below shows the currently supported attributes.

attribute type targets description
width integer floor, cellar size near X
height integer floor, cellar size near Y
length integer floor, cellar size near Z
character* string floor, cellar primary material the structure is made of
external_character* string floor, cellar secondary material the structure is made of
torches integer (0 to 5) floor, cellar quantity of torches, bigger value means smaller spaces between torches
flower-ratio float (0 to 1) garden quantity of flowers
tree-ratio float (0 to 1) garden quantity of trees
mushroom-ratio float (0 to 1) garden quantity of mushrooms

*supported values: stone, cobblestone, mossy_stone, sandstone, obsidian, wood, dark_wood, birch_wood, planks, dark_planks, metal, dirt, sand, red_sand, brick, stone_brick, dark_brick, glass, gold, diamond

Sometimes a source value doesn't fit the world element we use as target. In this case, we use conversions. At the moment, the following conversions are available:

  • to int
  • quantization
  • normalize
  • switch

The next example show a quantization conversion.

<conversion type="quantization">
    <parameter name="level0" value="1"/>
    <parameter name="level1" value="2"/>
</conversion>