gentelella/vendors/jqvmap/create/README.md

Creating Custom Maps for JQVMaps

Special thanks again to jvectormap for creating the base converter for this. I have flushed out the documentation a little more for any Python newbies out there ( like myself ).

Creating maps is actually a bit of work, and should really only be done by those familiar with Python & a Terminal Window, as these are the tools you will need to create maps. If you are OK with this, here is what you need to know to get started:

Requirements

Overview:

You will need to have the following installed:

1. Python ( 2.7+ )
2. GDAL ( OS Binary )
3. GDAL ( Python Package )
4. Shapely ( Python Package )
5. Booleano ( Python Package )

Installing Software:

Step #1:

Download & Install Python by clicking one of the Download Python buttons on the Python Website. We are using v2.7.10.

Step #2:

Open a Terminal window and make sure Python installed correctly by typing the following:

which pip

which should return something like ( if it did not, you did not install Python correctly ):

/Library/Frameworks/Python.framework/Versions/2.7/bin/pip

You may also wish to update PIP to disable upgrade warnings in the future:

pip install --upgrade pip

Step #3:

Now we need to install the GDAL/OGR binaries and follow the steps they layout for your designated OS.

OSX:

Download and install the GDAL 1.11 Complete Package.

Alternatively, If you have Homebew installed, you can run the following, though I personally had issues with it working 100%

brew update
brew install gdal

Windows:

You should be able to run Maptools custom MS4W installer to get everything you need.

Step #4:

With Python & GDAL Binaries installed, we can now install the required Python packages via the following Terminal Commands:

sudo easy_install GDAL
pip install shapely
pip install booleano

Note: If you have issues installing a Python Package, please visit the links in the Requirements Overview for detailed install instructions.

Downloading Map Sources

Before you can create custom maps, you need to download the vector data from the source. You will need to use a search engine to find the Shapefile for the map you want to create. This can usually be done by just searching for something like "New York Shapefile" or "Syria Shapefile" in Google.

Once you have the Shapefile you want, just download it and copy the unzipped directory of files you want to the ./create/source folder in this project.

If you would like to test the sample map config files we have in this project, you will need to download the following ( which are also good sources for maps in general ):

1. SHP/GeoDB Vector Themes from Natural Earth. Unzip the natural_earth_vector.zip file and copy the entire natural_earth_vector folder to the ./create/source folder in this project. TIP: If you plan on using this source, code_field is iso_a3 and name_field is name_long.

2. Global Administrative Areas has an updated Shapefile for pretty much every country. Just select the Country you want ( for this example, Syria ) and set File format to Shapefile and press the OK button to download. This will take you to a download page. Click the download link and save the zip file. For this example, unzip the SYR_adm_shp.zip file and copy the entire SYR_adm_shp folder to the ./create/source folder in this project. TIP: If you plan on using this source, code_field is ISO and name_field is NAME_ENGLI.

3. New York - Borough Boundaries (Clipped to Shoreline) from the NYC.gov website. Unzip the nybb_15d.zip file and copy the entire nybb_15d folder to the ./create/source folder in this project.

Creating Maps

Setup Environment

As detected by @andreasspeck you will need to add the following Environmental Variable to create more complex maps without issues. In a Terminal Window, run the following command before attempting to create a map:

export OGR_ENABLE_PARTIAL_REPROJECTION=TRUE

If you plan on creating multiple maps in the future, you may wish to just add that line above to your profile by editing your .bash_profile, .profile or .zshrc file ( whatever you are using OS ).

If you choose to edit your profile, make sure you run the source command to add it to your current Terminal session.

source .bash_profile

Map Configurations

You can create a custom JSON file and save it in the ./create/config folder.

A sample my-map.json configuration file would look something like this:

[
  {
    "name": "read_data",
    "file_name": "./source/some-folder/some-file.shp"
  },
  {
    "name": "write_data",
    "format": "jqvmap",
    "file_name": "./output/jquery.vmap.my-map.js",
    "params": {
      "code_field": "iso_column",
      "name_field": "name_column",
      "name": "my-map"
    }
  }
]

You will need to pay special attention to what the code_field and name_field parameters are, as these are what are used in the map creator. These are usually found along side your .shp file as either an .csv file or .xml. You might need to use a DBF Viewer to view the .dbf file if a CSV & XML don't exists.

For code_field you are just looking for the column name that has the ISO Code ( 2-3 letters ).

For name_field you are just looking for the column name that has the ISO Name ( English Name ).

Once you have created a config file, and set the file_name for read_data and write_data, you can run the following command in a Terminal Window.

cd /path/to/jqvmap/create
python jqvmap.py config/my-map.json

The map creator will output the new JQVMap files into the ./create/output folder.

Sample Map Configurations

We have already setup a few custom config files for you to play with. With a Terminal Window open, run the following commands ( make sure to change /path/to/jqvmap to wherever you have this project installed. ):

cd /path/to/jqvmap/create
python jqvmap.py config/continent.json
python jqvmap.py config/new-york.json
python jqvmap.py config/syria.json

Map Configuration JSON Options:

The following are the complete list of JSON configuration options for you to use. Make sure to look at the samples in the config folder to get an idea on how to use these with your map.

Command	Config	Option	Description
read_data			Read geometries from GIS data file
	file_name		The name of the file to read
	longitude0		Central meridian coordinate
	projection		The map projection to use, currently implemented projections are merc (Mercator), mill (Miller Cylindrical), aea (Albers Equal Area) & lcc (Lambert Conformal Conic)
write_data			Writes geometries to file
	file_name		The name of the file to write
	format		Format of data to write, jqvmap for JQVMap compatible format, no value for OGR format
	params		Hash with parameters to supply to writer, the following parameters are used in case of jqvmap format:
		code_field	Name of field to use as a region code
		name_field	Name of field to use as a region name
		name	Map base name
union			Merges geometries with the same value for one field
	by		The name of the field to merge geometries by
join_data			Adds or rewrites properties for geoemtry based on equal values in another field, works similar to JOIN operation from SQL
	data		This could raw data to join or file name of CSv file with data to load
	fields		Array describing fields, which data contains
	on		Field to match to join data
remove			Removes geometries and their properties based on logical expression
	where		Expression to evaluate for each geometry
remove_fields			Removes fields and associated properties
	fields		Array with field names to remove
remove_other_fields			Removes all fields and associated properties except the ones provided
	fields		Array with field names to preserve
buffer			Removes (erosion) or adds (dilation) zone around every geoemtry
	distance
	resolution
simplify_adjancent_polygons			Simplifies polygons taking topology into account (shared borders remain shared after operation)
	tolerance		Simplification tolerance
intersect_rect			Cuts out everything beyond boubdaries of supplied rectangle
	rect		Array with four values, defining left-top and right-bottom corners of rectange
remove_small_polygons			Removes polygons which area is less than supplied value
	minimal_area