Theme API Documentation
iXMaps is a vector graphic mapping framework, based on SVG files generated from shape files and QGIS projects, and a Javascript library to geographically handle these SVG files.
The iXMaps Javascript library enables the map for thematic mapping either by changing properties of the map shapes (choroplethe themes), or creating new SVG graphical objects to visualize the data by various chart types which are positioned either on map items, or by geographical coordinates (latitude, longitude) defined by the data.
iXMaps defines a high-level visualization grammar for thematic maps. It provides a concise JSON syntax for supporting rapid generation of visualizations from raw data.
At its core, iXMaps theme specifications are JSON objects that describe visualizations as mappings from data to properties of geographical map objects (polygons or lines) or graphical marks (e.g., points, bars, etc ) bound to geographically defined positions or objects on the map.
Because with iXMaps themes are 'alive' and not images, every theme can be customized to adapt colors or chart types and sizes. Than if you like, you can share the customized map by generating a new URL containing the customized map and theme parameter
The theme definition object can be serialized and joined as a parameter to an URL. In consequence every thematic map can be represented by a URL which combines the HTML template, the Tile map service, the SVG map and the theme definition.
iXMaps themes are always created from raw data, given by a data URL, so if the data changes, the theme follows. By defining a refresh interval, you can have almost real time data showed in the theme.
iXMaps supports:
Choroplethe themes require an 'id' of the map elements to be used for the theme.
Chart themes can be positioned on the map either by the id of map elements or by geographical coordinates, if present in the data.
Themes are defined by a JSON Object using the iXMaps high-level visualization grammar and realized by a iXMaps API function.
You may define the theme first and call it or define the theme inside the function call. You can also wrap it all together into a HTML link and place the theme function in the 'href' attribute.
// define the theme
var theme1 = {
"layer": "com2011_s",
"field": "Totale complessivo",
"style": {
"type": "CHOROPLETHE|EQUIDISTANT",
"colorscheme": [ "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
"dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
"lookupfield": "comune"
}
}
// put the theme on the map
ixmaps.newTheme("Totale complessivo",theme1,"clear");
This is the minimal definition of a chloroplethe theme based on named shapes within the SVG map. The basic properties are:
Property | Type | Description |
---|---|---|
layer |
string |
Defines the layer of the map used by this theme. This layer must provide the topology for choroplethe themes or may define points to position charts on. In these cases, the entities of the layer must have IDs generated that correspond to the cell values of the data colums defined in the 'style' parameter "lookupfield". |
field |
string |
Defines the field (column name) of your data, where to find the values of your theme |
style |
object |
Defines the type and the layout of the theme in Javascript object notation (JSON); |
If you want to use a layer (in ixmaps layer items are SVG groups with unique ID attribute) for choroplethe themes, or as anchor for chart positioning, the layer must be created with appropriate ID's (which correspond to the data field, you define in the theme)
Note: for chart themes it is possible to position the charts at geografic coodinates defined by latitude and longitude. For this case in the 'lookupfield' you define 2 fields, that will contain the lat/lon pair, separated by "|".
Example:
"lookupfield": "Lat|Lon"
Defines the type and the layout of the theme in Javascript object notation (JSON)
{ property1:value, property2:value,... }
A list of all possible parameter you find here
Let's have a look on the definition from the above minimal example:
"style": {
"type": "CHOROPLETHE|EQUIDISTANT",
"colorscheme": [ "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
"dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
"lookupfield": "comune"
}
Property | Type | Description |
---|---|---|
type |
string |
defines the type of the theme. This is the graphical representation, which can be a
colorized shapes
(CHOROPLETHE), or
chart objects
(bar charts, pies, donuts,...).
A type definition is a string with a combination of type variables, separated by '|'. Sample: 'type:CHOROPLETHE|EQUIDISTANT' |
colorscheme |
array |
defines the colors to be used in the theme (default: momochrome blue) |
dbtable |
string |
associate an external (javascript) database table to this theme; value:name of the table (without suffix!) sample: 'dbtable:layerdb' |
lookupfield |
object |
define a field of the above external table which values can be used to find the theme shapes; sample: 'lookupfield:statename' |
The simples way to realize a theme is to define it as a JavaScript object and realize it with the appropriate iXmaps API call ixmaps.newTheme(" ... title ...",themeObj,[flag]).
For the above example this would lead to:
var theme1 = {
"layer": "com2011_s",
"field": "Totale complessivo",
"style": {
"type": "CHOROPLETHE|EQUIDISTANT",
"colorscheme": [ "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
"dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
"lookupfield": "comune"
}
}
ixmaps.newTheme("Totale complessivo",theme1,"clear");
You can also put it all together to a function call
ixmaps.newTheme("Totale complessivo",{
"layer": "com2011_s",
"field": "Totale complessivo",
"style": {
"type": "CHOROPLETHE|EQUIDISTANT",
"colorscheme": [ "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
"dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
"lookupfield": "comune"
},"clear"
});
or define it all in your HTML within an <a> tag
<a href='javascript:ixmaps.newTheme("Totale complessivo",{
"layer": "com2011_s",
"field": "Totale complessivo",
"style": {
"type": "CHOROPLETHE|EQUIDISTANT",
"colorscheme": [ "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
"dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
"lookupfield": "comune"
}
},"clear"
);'> Totale complessivo</a>
Themes are defined by JSON objects, like in the example shown below, and realized with the appropriate iXmaps API call ixmaps.newTheme(" ... title ...",themeObj,[flag]).
var theme1 = {
"layer": "com2011_s",
"field": "Totale complessivo",
"style": {
"type": "CHOROPLETHE|EQUIDISTANT",
"colorscheme": [ "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
"dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
"lookupfield": "comune"
}
}
ixmaps.newTheme("Totale complessivo",theme1,"clear");
There are the following main arguments to define, to describe a theme:
layer |
string |
defines the layer of the map to be the reference for this theme. For choroplethe themes this layer will provide the topology to colorize, for charts it may define points to position charts on. In both cases,the entities of the layer must be identified and the ID's must correspond to the values in the data column defined by the 'style' parameter "lookupfield". |
field |
string |
defines the field (colum name of table) of your data, where to find the values of your theme; this can be only one field, or a sequence of fields (column names) separated by '|'; example: 'col1|col2|col3' |
field100 |
string |
defines the field of your data, where to find a 2nd values for percent, difference or other value operations |
style |
object |
defines the type and the layout of the theme in Javascript object notation (JSON) |
The last object defines the nearly everything of the theme. Lets have a look on the fundamental objects of the sample theme definition:
The 'style' object must at least have 4 elements to define type, color scheme, data source and lookup field for the theme as you can see in the above example
Property | Type | Description |
---|---|---|
type |
string |
defines the type of the theme. This is the graphical representation, which can be a
colorized shapes
(CHOROPLETHE), or
chart objects
(bar charts, pies, donuts,...). A type definition is a string with a combination of type variables, separated by '|'.
Example:
|
colorscheme |
array |
defines the colors to be used in the theme (default: momochrome blue)
Example:
|
dbtable |
string |
defines the data to use by the theme. the value is a sequence of parameter to define:
Example:
|
lookupfield |
object |
define the name of the row of the above defined data table, where to find the values which can be used to identify the layer items (shapes or points) for the theme creation. Example:
|
Lets have a look on the 4 objects
With the 'type' keywords you define the nature of the theme by basic types and modifyers
there are 2 different theme types | ||
TYPE_ID | Type | Description |
---|---|---|
CHOROPLETHE |
string |
defines a theme based on map shapes (polygons) that will be colored by value classes and a color scheme |
CHART |
string |
defines a theme visualized by charts positioned on the map |
and the following basic CHART types | ||
TYPE_ID | Type | Description |
BUBBLE |
string |
simple circle bubbles with size and color options and optional value display |
SQUARE |
string |
rectangulars with size and color options and optional value display |
BAR |
string |
bars, barcharts with several bars and stacked bars |
POINTER |
string |
bars with a pointing top, usefull if we have ranges from negative to positive values |
PIE |
string |
pie chart with one or more parts |
DONUT |
string |
a donut chart with one or more parts |
SYMBOLS |
string |
a theme visualized by symbols on the map |
BUFFER |
string |
a special theme to create one or more buffers around map
objects, which can be points, lines or shapes;
|
these basic types can be used in combination with the following modifier to define the final chart type | ||
I. methods to create the class ranges for color schemes: | ||
TYPE_ID | Type | Description |
EQUIDISTANT |
string |
equidistant value classes |
LOG |
string |
logarithmical value classes |
QUANTILE |
string |
quantile value classes; same number of members in every class |
EXACT |
string |
every value represents a color class |
DOMINANT |
string |
with multiple fields, show the color of the field with the highest value |
PERCENTOFMEAN |
string |
with multiple fields, show the color of the field with the deviation from mean (in %) |
DEVIATION |
string |
with multiple fields, show the value with the highest deviation (in standard deviation) |
OFFSETMEAN |
string |
with multiple fields and type CHART, show the deviation
of all fields by +/- pointers: |
RANGES |
string |
class ranges are defined explicitly by a 'ranges' parameter; example:
|
II. defining the value algorithm | ||
TYPE_ID | Type | Description |
DIFFERENCE |
string |
value = [field] - [field100] |
FRACTION |
string |
value = [field]/[field100] |
PERCENT |
string |
value = [field]/[field100]*100 |
PERMILLE |
string |
value = [field]/[field100]*1000 |
RELATIVE |
string |
value = [field]/[field100]*100 - 100 |
INVERT |
string |
value = 100 - [field]/[field100]*100 |
CALCVAL |
string |
value = Math.round([field]*[field100]/100) |
CALC100 |
string |
value = Math.round([field]*[field100]/100) |
PRODUCT |
string |
value = [field]*[field100] |
NEGATIVEISVALUE |
string |
allow negative values |
ZEROISVALUE |
string |
allow zero values |
SUM |
string |
define the aggregation mode; if values are absolute, you
may define 'SUM'; |
chart size methods | ||
TYPE_ID | Type | Description |
LINEAR |
string |
the size of the chart graphics represents the value |
VOLUME |
string |
for 3d charts; the volume of the chart graphic represents the value |
SIZE |
string |
for 2d charts; the surface of the chart graphic represents the value |
SIZEP4 |
string |
for wider value ranges, this uses power of 4 to flatten the chart sizes |
SIZELOG |
string |
use the logarithm of the value to size the chart graphics |
dynamic opacity for choroplethe themes | ||
TYPE_ID | Type | Description |
DOPACITY |
string |
dynamic opacity by the value; lower values get transparent |
DOPACITYMIN |
string |
dynamic opacity to emphasize the minimum values; higher values get transparent |
DOPACITYMAX |
string |
dynamic opacity to emphasize the maximum values; like DOPACITY but you can apply the style variables 'dopacitypow' and 'dopacitypow' to define custom opacity curves |
DOPACITYMINMAX |
string |
emphasizes minimal and maximal values; the average values get more transparent |
BIPOLAR |
string |
same as DOPACITYMINMAX |
DOPACITYLOG |
string |
like DOPACITYMAX, but takes the logarithm of the values to scale the opacity |
DOPACITYMEAN |
string |
like DOPACITY, to use with DOMINANT, PERCERTOFMEAN or DEVIANT |
chart type modifier | ||
TYPE_ID | Type | Description |
SEQUENCE |
string |
make a composite chart of n BUBBLE, SQUARE, BAR or SYMBOL;
this means a chart composed of a sequence of graphics of the
defined type, positioned in a defined way relative to the
center of the chart; see chart positioning
below. |
STARBURST |
string |
PIE or DONUT modifier; make radius variable by value; |
3D |
string |
make BAR, PIE or DONUT tree dimensional |
SIZE |
string |
with PIE or DONUT, the radius represents the value |
HEIGHT |
string |
with PIE or DONUT, the char height represents the value |
WIDTH |
string |
with PIE or DONUT like SIZE; with POINTER, makes the pointer width more dynamic by value |
VOLUME |
string |
with BAR or PIE; width and height represent the value; bars get cubes |
chart positioning and part sorting | ||
TYPE_ID | Type | Description |
CENTER |
string |
the chart, or the single graphics of a composed chart are positioned on the center of the chart position. |
LEFT |
string |
the chart is aligned to the left of the chart position. |
RIGHT |
string |
the chart is aligned to the right of the chart position. |
TOP |
string |
the chart is aligned to the top of the chart position |
BOTTOM |
string |
the chart is aligned to the bottom of the chart position |
ABOVE |
string |
like TOP |
BELOW |
string |
like BOTTOM |
HORZ |
string |
BARs and MULTIPLE or SEQUENCE charts are composed
horizontally; default is vertically |
STAR |
string |
the single graphics of a composed chart are positioned around the center of the chart position with the first graphic on the center and the following around the first with the radiuses touching each other. |
SORT |
string |
the graphics are sorted by their values; default is sort down; if not defined, the graphics are drawn in the order of the field definition |
UP |
string |
sort up, the smallest value is on the top |
DOWN |
string |
sort down, the biggest value is on the top |
RANDOM |
string |
sort the graphics by random; every chart gets its own 'composition', this is useful with STAR charts, to avoid pattern forming |
miscellaneous | ||
TYPE_ID | Type | Description |
AGGREGATE |
string |
aggregate values of the same position before creating the
charts; this is useful if you have a dataset with multiple
records for the same position. |
DIFFUSE |
string |
only with 'gridwidth': like AGGREGATE, but with a slightly different algorithm; every value is distributed to the nearest 4 points of the aggregation grid; every of the 4 points gets a portion of the value relative to the distance to the original position of the value. |
MULTIPLE |
string |
if you have a dataset with multiple records for the same position, this type modifier adds an offset to every repeated position, so you see every value displayed; normally the offset is added in Y-direction; you can change this by the modifier HORZ. you can define rows by the style parameter 'gridx'; example: 'gridx':'3' means that every 3 offsets a new row will be started. |
VALUES |
string |
add a textual value display to CHOROPLETHE or CHART themes |
VALUESBACKGROUND |
string |
create a colorized background for the textual value representation of CHART themes |
BOX |
string |
create a background box around every chart; the box can be customized by the style parameter: 'boxopacity', 'boxborder' and 'boxmargin' described below. |
MOVABLE |
string |
makes charts movable; this means you can drag the charts on the map to any desired position. |
Property | Type | Description |
---|---|---|
colorscheme |
array |
a colorscheme is defined by an array of 1 - n values
the values may define directly 1 - n colors
Example: or a dynamic color scheme defined by:
Example: |
The simplest colorscheme is one color definition, like shown below:
"colorscheme": [ "#FF0000" ]
or defined by RGB notation:
"colorscheme": [ "RGB(255,0,0)" ]
or the color name:
"colorscheme": [ "red" ]
If you need more colors, you can define them directly:
"colorscheme": [ "#FFFDD8","#FFEBB2","#FED992","#FCBA6C","#F99E5B","#E86144","#B5284B","#952D44" ]
or by a generated color scheme.
"colorscheme": [ "8","#FFFDD8","#952D44" ]
Property | Type | Description |
---|---|---|
type |
string |
defines the nature of the theme, for details see description of 'type' above |
colorscheme |
array |
defines the colors to be used in the theme (default: momochrome blue)
Example:
|
nodatacolor |
string |
define the color, that will be displayed if there is no value for the item |
linecolor |
string |
define the line color of PIE or BAR charts |
opacity |
number |
defines the overall opacity of a theme (CHLOROPLETHE and CHART) |
autoopacity |
boolean |
if set to TRUE, the opacity of CHLOROPLETHE themes depends on the map actual zoom; zooming in the theme gets more and more transparent (to show details of the base map) |
fillopacity |
number |
defines the opacity of surface filling in CHART themes |
shadow |
boolean |
if set to TRUE, charts are displayed with a drop down shadow |
aggregation |
string |
define the aggregation algorithm: may be 'sum' or 'mean' (default is 'mean') |
evidence |
string |
defines how selected items (points, lines, polygons) shall be marked |
dfilter |
number |
define a filter for PERCENTOFMEAN |
overviewchart |
string |
defines the 'type' of the overview chart, which is the sum or class chart shown in the theme legend; default: NONE |
define data sources | ||
dbtable |
string |
defines the data source of the themes |
dbtableType |
resource |
defines the type of the data source of the themes, (csv, json, FT) |
dbtableUrl |
string |
the URL to the data source |
dbtableEXT |
string |
a Javascript function to call if data is loaded |
define data columns | ||
itemfield |
string |
the field (column name) where to take the value from, alternative to the definition in 'fields' |
lookupfield |
string |
the column/s of the data which
cells define the relationship to the map;
these can be:
|
lookuptoupper |
boolean |
if TRUE, lookup cell values are changed toUpper before
matching the corresponding ID on the map |
lookupsuffix |
string |
if TRUE, the define suffix will be appended to all lookup cell values before matching the corresponding ID on the map |
exclude |
array |
you may define map item IDs to exclude from the theme display; example; "exclude" : "Lichtenstein,Monaco" |
theme calcolation | ||
ranges |
string |
define value ranges for themes with color classes defined by a colorscheme, you must define n+1 values for n colors
in the above example there are 4 ranges with:
|
rangecentervalue |
string |
for EQUIDISTANT class distribution, you can here define the center of the classes; EQUIDISTANT automatic class definition takes the lowest and the highest value and divides the range into n equal parts. If you define a 'rangecentervalue' the range will be symmetric to this value; this means either the min or the max value will be adjusted to fulfill this condition. |
values |
array |
for EXACT theme types, you may want to define the allowed values or you can use this definition option to give an order to the possible EXACT values; note: EXACT values are strings. |
symbols |
array |
define the symbols for 'type' SYMBOL; this can be IDs of loaded symbols defined in SVG or generic symbol shapes created 'on the fly'. The generic symbols are: circle, square, diamond, triangle, label The default symbol is 'circle' |
align |
string |
define the alignment for CHART themes; possible values are: center, top, bottom, left, right, above, below; you can combine align values; example: "align" : "above|left" |
sizefield |
string |
the name off the data column to use to size the charts |
buffersize |
string |
the size of BUFFER charts to draw around points, lines or areas (in meter) |
bufferstep |
string |
the amount of buffer size changes (meters) |
field100min |
string |
clips the charts drawn by defining a minimum value for the 'field100' values; useful if you want to make a theme with percentages to exclude values based on few items |
fractionscale |
string |
defines a scaling factor for values created with the FRACTION 'type' modifier |
minvalue |
string |
minimal value, values below this are not shown |
normalsizevalue |
string |
you can define the value that will produce a chart of a normal size, which is 30 pixel |
scale |
string |
define a scaling factor (0 >x<100) to scale the chart size |
weights |
string |
the values from the theme data cells can be 'weighted' by a floating-point factor; here you can define n factors for n fields (data columns); example: "weights" : "1,1,0.5,1" will scale the values of the 3. data column by 0.5 |
texts | ||
units |
string |
give a unit to the value display: example "units":"%" leads to value display like "56 %" |
units100 |
string |
also the value100 (e.g. 100% value) can have a unit displayed |
sizevalueunits |
string |
if you define a 'sizefield', you can give it a unit within the char info display; example "sizevalueunits" : "residents" |
legendunits |
string |
you may define value units, only used within the theme legend |
xaxis |
array |
for BAR charts with multiple bars, you can define a x-axis description; example you have 3 bars with values for 2012, 2013 and 2014, then yuo can define the x-axis text with: "xaxis" : "2012,2013,2014" |
label |
array |
define legend label, the value label in the theme legend display are preset with the column names you defined to get the data; here you can overwrite them with more readable or sigificant text: "label":"label1,label2,vabel3" |
title |
string |
define the title of the theme, to show in the theme legend |
snippet |
string |
define a short description to use in the theme legend and in chart info bubbles |
description |
string |
define a description to use in the theme legend and in chart info bubbles |
infotitle |
string |
define a title for all chart info bubbles |
titlefield |
string |
the name off the data column to use as chart info title |
snippetfield |
string |
the name off the data column to use as short description in the chart info |
labelfield |
string |
the name off the data column to use as chart label |
showdata |
string |
show the original data of the chart within the chart info bubble |
textplacement |
string |
??? |
textual value display | ||
valueupper |
string |
define an upper map scale value to suppress value display if you zoom out the map; e.g. "valueupper":"1:100000" shows values only if the map scale is lower than 1:100000 |
valuescale |
string |
show bigger or smaller value texts |
clipvaluesize |
string |
show values only if the dynamic text size (which depends on the chart size) is greater than the defined value (pixel) |
fadevaluepow |
string |
defines the power (x power n) of value display transparency depending on the value size; higher power leads to faster transparancy |
fadenegative |
string |
defines the opacity of negative values ( 1 ... 0.1 ) |
alpha channel (choroplethe themes) | ||
alphafield |
string |
the name off the data column to use to create CHOROPLETHE themes with dynamic opacity |
alphafield100 |
string |
the name off the data column to use with 'alphafield' to
calculate the value for dynamic opacity; |
dopacityscale |
string |
defines a factor to apply to dynamic opacities calcolated by a dedicated value (see DOPACITY and alphafield) |
dopacitypow |
string |
defines the power (x power n) for the dynamic alpha calculation; it is comparable to the contrast for images (see DOPACITY and alphafield) |
dopacityramp |
string |
(deprecated) same as dopacitypow |
for theme with 'timeline' (CLIP) | ||
clipframes |
string |
the number of frames for CLIP themes |
cliplegend |
string |
a text to display while CLIP themes are running |
clipparts |
string |
clip the number of parts of a theme |
multiple values for the same position (MULTIPLE) | ||
gridx |
string |
a x-axis grid width for MULTIPLE themes |
background box for charts ('BOX') | ||
boxopacity |
string |
with type modifier BOX: define the opacity of the chart background box |
boxmargin |
string |
with type modifier BOX: define the margin (pixel) of the chart background box |
bordercolor |
string |
with type modifier BOX: define the color of the border of
the
chart background box, |
borderstyle |
string |
with type modifier BOX: define the border style of the
chart background box; |
borderwidth |
string |
with type modifier BOX: define the width (pixel) of the border of the background box |
borderradius |
string |
with type modifier BOX: define the corner radius (pixel) of the chart background box |