Using the Map Converter

The Map Converter converts ESRI shapefiles to a JSON format suitable to be displayed in a Dojo geocharting component (dojox.geo.charting package). The Map Converter is a Dojo application connected to a REST service running on a server. Computation is done on the server. The converted files can be queried by the client.
The server implements some services, such as uploading files to the server, reprojecting map files, simplifying map files, and converting map files into JSON format.

Provide input parameters

You must provide a set of input parameters for the conversion.
  1. Upload shape files to the server
    This action must be performed first to be able to use the Map Converter.
    1. In the Conversion Settings panel, click the Upload button.
      Or
      In the Uploaded Files panel, click the Upload button.
    2. Select the files you want to upload.
      For each map, the Map Converter requires at least two files, the .shp file and a .dbf file. The .shp file contains the shapes of the map features. The .dbf file contains metadata associated with each map feature. To select multiple files, hold the control key while you select the files. Multiple selection is not available for Internet Explorer browsers. If you are using Internet Explorer browser, you must upload each file one by one.
    3. Upload the files.
      Click Open to upload the selected files.
      You can see the list of uploaded files on the server in the Uploaded Files panel. This list is not a per-session or authenticated file list. It shows all the files uploaded on the server, including the files uploaded by other clients.
      This panel provides an option to delete files from the server. If you want to delete files on the server, delete only files that you have uploaded. To delete a file, select it and click the delete button.
  2. Select the file to convert
    In the Conversion Settings panel, from Shapefile, select the file that you want to convert.
  3. Associate metadata with map features
    In Feature name, select metadata that is appropriate to your application.
    You select the metadata to be associated with each map feature to identify the feature and to bind it with the data store in the dojox.geo.charting widget. Values corresponding to the metadata are displayed in the Map Preview pane as tooltips. For example, selecting NAME causes the ISO country identifiers to be displayed as tooltips.
  4. Select input projection
    Select the appropriate input projection.
    Usually the input projection is the projection labeled Longitude/Latitude, which is a geographic position. If the Shapefile has been encoded with a different projection, select that projection from the list.

Provide output parameters

You must provide a set of output parameters for the conversion.
  1. Select and test the output projection
    1. Select the output projection
      Select the output projection that seems appropriate for your map.
      This parameter specifies the projection in which the converted map is projected. If you select the same projection as the input projection, the map will not be projected. Not all the listed projections are valid for every map. Unexpected results can occur when unsuitable projections are selected.
    2. Visualize the result
      Click Convert.
      The converted map is displayed in the pane on the right.
  2. Select type of coordinates
    Select integer or floating-point coordinates for the converted JSON map.
    Floating-point coordinates are selected by default. Integer coordinates must be explicitly selected. Selecting integer coordinates usually results in a smaller JSON file. In this case, you might have to choose a Scale Map to value for the map to increase precision. The default value usually works well.
  3. Select Minimum detail size
    Enter Minimum detail size to obtain a lighter, but less detailed map.
    The minimum detail size is expressed in meters. It indicates that no details in the converted map will be larger than this distance. This parameter is used to obtain a smaller JSON file.
  4. Remove unwanted artifacts
    Select Wrap dateline.
    Under certain circumstances, projecting a map can produce some unwanted artifacts, especially when projecting a world map. This option can remove such glitches, but requires more time to project the map.

Download converted file for use in an application

When you are satisfied with the results of the conversion:
  1. Download the file
    Click Download to download the converted JSON data.
  2. Integrate the data in an application
    Integrate the data generated by the Map Converter as map description data in a dojox.geo.charting widget.
    The following example assumes that you downloaded the JSON data as a file named map.json and shows how to use it.
    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" 
    	"http://www.w3.org/TR/html4/strict.dtd">
    <html lang="en">
    <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Use Map Converter Data</title>esources/UploaderFileList.css">
    <script type="text/javascript">
    	var djConfig = {
    		parseOnLoad : true
    	}
    </script>
    <script type="text/javascript" src="../../../dojo_current/dojo/dojo.js"></script>
    <script type="text/javascript">
    	require([ "dojox/geo/charting/widget/Map" ]);
    </script>
    
    </head>
    
    <body class="claro">
    	<div data-dojo-type="dojox.geo.charting.widget.Map"
    		shapeData="map.json" />
    </body>
    </html>