sn-smj v2.0.0

SMJ - Sennon Map JSON

This utility converts shapefiles to a single .smj file which has all the necessary information for maps to display points with Google Maps, as well as handle layer toggles, map key information and anything else needed to display the data points correctly on the map.

Installation

smjconfig.json explained

This file will be interpreted as a json file with a very specific structure that allows the smj libraries to build its layer objects and manage other tasks. Any object in the file can be left out, which only results in nothing happening, but the point is that any feature available can be indepedently selected. Since the goal of the smj library is to leave any if not all of the work to itself, any specific configuration that is needed must be set up in the .smj file that is loaded.The mapDefault object is essentially just passed on to the output without affecting anything since it is only a handy way to set the default position of the smj library object.

{
	// If this object is defined, the map will update its initial starting point to this value.
	// 
	"mapDefault": {
		"lat": 37,
		"lng": -75,
		"zoom": 6 // Note that zoom goes from 1 (far from earth) to 20 (close to earth), both values included. 
	},

	// This next array defines geofencing regions and values returned
	"geofence": {
		
		// A geofence object defines a border or multiBorder and a return property value
		// The property can be any final property in the smj file, so an addProperty value can be used
		// The key is used by the smj library to know which geofence to check with the get or watch functions
		// The default value is returned in case geofencing doesn't return a current feature or that the feature does not that the property set
		"links": {
			"layer": 0,
			"value": "link",
			"default": "www.com"
		}
	},

	// The layers object is the base of the .smjconfig file
	"layers": [

		// A border layer represents an array of borders, each which their own properties. The drawing details are used by all the borders.
		{

			// The file is the name without the .shp extension that will be loaded for that layer.
			"file": 			"BORDER",

			// The shapefile's projection, needed to get correct coordinates in output value.
			"tsrs":				"EPSG:4326",

			// The type of the layer, which is used to know how to format the data.
			"type": 			"border",

			// The resolutions array is used to define resolutions needed.
			// The smj library will always attempt to use the lowest resolution it can find at certain zoom levels.
			// If a data set is smaller and doesn't need to be simplified, then the resolutions array isn't needed.
			"resolutions": 		["0.5", "0.25", "0.03"],

			// The string entries in the array are used to keep property values for features in the final output.
			// If no properties object is defined, then no properties will be saved.
			// If it is an empty array, then all properties are saved.
			"properties": 		[
			],

			// The add properties array is used to inject extra information about a feature in the final output.
			"addProperties":	[

				// If there is only 1 element in the entry, it is expected to be an array tha has the same amount of entries as features for the layer and that they are in the same order.
				// If there are 3 elements in the entry, the first is the property name to check against, the second is the name of the property to add, and third is an object where each key is the property value that needs to match and its value is the property to add. This way of adding properties is safer since the amount of features affected by the property and the order don't matter. The good feature will be found before adding the property value.
				[
					"NAME",
					"link",
					{
						"ADAIR": "www.com"
					}
				],
			],

			// The details object defines how the layer should be drawn. For multiBorders and borders the array has 3 entries.
			"details":		[

				// The stroke color, which is derived from the hex value, that is applied to all the borders
				// The hex values can be either 3/6 (RGB/RRGGBB) or 4/8 (RGBA/RRGGBBAA) characters long.
				"#000",

				// The stroke width
				1,

				// Since borders always use fill, this sets its opacity and the fill color will be the same as the stroke color.
				0
			],

			// The toggle property is used by the smj library to return an array of strings, where each string is the name of a toggle button. Once the layers are done being set up, the smj library will go through each to find toggle values. Each layer can have any amount of toggle values, and they can overlap. This means that a toggle can be the same for multiple layers, and a layer can be toggled by more than button. For example, including an all toggle would have to turn off all layers, but the individual layer toggles need to be taken into account.
			// The toggle value will be the name of the returned toggle entry when asked for them.
			"toggle": [
				"Counties"
			],

			// The mapKey property will be used like the toggle property, as a way to return information for the app using smj to set itself correctly. The map key values are also generated and returned by the smj library based on the found values in the layers. Generally, each layer only has 1 map key entry for it since the whole layer "looks" the same. Obviously, this isn't true for muliBorder layers, which is why the mapKey value is expected to be an array where the entry names match up with the details color array. This is so that the map key can know which color to display next to the feature name.
			"mapKey": "Counties"
		},

		// A multiBorder layer is essentially the same as a border layer, with the difference being that each border gets its own color and map key information because those layer values are expected to be arrays and not just the value. Each array item index is used to determine which border is affected.
		{
			"file": 			"MULTIBORDER",
			"tsrs":				"EPSG:4326",
			"type": 			"multiBorder",
			"resolutions": 		["0.5", "0.25"],
			"details":		[

				// Here the difference with a border layer is that the color values are in an array where each feature should get a color value, otherwise the default gets used for that border.
				["#000", "#001"],
				1,
				0
			],

			// MultiBorder layer mapKey information should be an array that matches the colors.
			"mapKey": [
				"Territory 1",
				"Territory 2"
			]
		},

		// A line layer is like a border but without the fill. Also, since most lines aren't going to be used for geofencing or interacted with, properties are rarely needed. For better performance, a lineID property can be set which will be used to reassemble line sections.
		// Since the geojson format can wind up making what should be a single line into many smaller line sections, each with its own set of properties, this can be very inefficient to display. To help with this issue, the line section property should identify to which bigger line each section belongs to, so that they can be reassembled into much fewer, longer lines.
		// Since a line section ends on the same coordinate another starts, by recombining lines, the map has 1 point less to draw and 1 fewer polyline object to manage per combined line. This can add up to a big boost in performance.
		{
			"file": 			"LINES",
			"tsrs":				"EPSG:4326",
			"type": 			"line",
			"resolutions": 		["0.5", "0.25"],
			"lineID":			"LINESEC"
			"details":		[
				"#000",
				1
			]
		},

		// A point layer respresents a list of features where each has only 1 coordinate, its position, and any properties saved or added to it.
		// Points will become markers on the map and when tapped, an info window displaying the properties will be shown, if properties are found.
		// The other difference with other layers is that the details array is expected to contain the name of the image to use for that layer's markers.
		{
			"file": 			"POINTS",
			"tsrs":				"EPSG:4326",
			"type": 			"line",
			"resolutions": 		["0.5", "0.25"],
			"properties": 	{
				"switchID": 		"SWITCHID",
				"location": 		"LOCATION",
				"type": 			"TYPE",
				"structureNumber": 	"STRUCT_NUM",
				"ampRate": 			"AMP_RATE"
			},
			"details":		[
				"SwitchImage"
			]
		}
	]
}

Installation

Run

npm install -g sn-smj

from the console.

Examples

Typical use

Calling this will look for .smjconfig files in the shapefilesfolder path and convert the necessary files to build the final .smj output file. Using the -v argument prints information about what smj is doing, otherwise the conversion is silent.

smj shapefilesfolder -v

• Using node smj.js is essentially the same as using ./node.js.
• The -v argument can also be -verbose, but no other second argument can be used, otherwise an error is shown.
• After determing what needs to be converted and how with the .smjconfig files, the final output has the same name as its config, but with a different filetype.
• The output file is located in the directory from which smj is called, and the shapefiles folder passed can be anywhere as long as the path to the folder is relative.