/wms

RASTER

The raster mode is used to rasterize points, shapes, symbols, and/or tracks from one or more tables. Available parameters are:

Styling parameters must be specified for each table provided in the LAYERS parameter. For instance, if LAYERS=LAYER1,LAYER2 then to set different point colors for each layer the syntax would be: POINTCOLORS=FF0000,0000FF. In this case points from LAYER1 would be rendered as red while points from LAYER2 would be rendered as blue. If styling parameters are not provided for a layer, the default value is applied.

All colors must be provided in hex notation in the format RRGGBB or AARRGGBB (to specify the alpha value). For example, opaque red may be given as FF0000 or FFFF0000.

To use symbols rather than points, the source table(s) must have a string type column named SYMBOLCODE, which contains the desired symbol's identifier. All necessary symbols need to be added via the /insert/symbol endpoint. The IDs in the SYMBOLCODE column must match up with the IDs of the inserted symbols. To use a non-default column for symbols or to change a symbol conditionally, use the SYMBOL_ATTR parameter. For example, you can change the displayed symbol conditionally depending on a record's vendor_id using the following SYMBOL_ATTR statement:

SYMBOL_ATTR=case(vendor_id,{'YCAB','NYC'},{'taxi_blue','taxi_green'},'taxi_black')

For example, to generate a raster image from a table nyc_neighborhood with the following characteristics:

• The geometry data is extracted from the nyc_neighborhood table's geom column
• SRS is EPSG:4326
• Bounding box longitude is from -74.1 to -73.9 and latitude is from 40.6 to 40.9
• Image size is 1024 x 1024
• The raster image will render shapes because DOSHAPES is set to TRUE

1
2
3
4
5
6
7
8
9

${KINETICA_URL}/wms?REQUEST=GetMap
&STYLES=raster
&LAYERS=example_geospatial.nyc_neighborhood
&GEO_ATTR=geom
&SRS=EPSG:4326
&BBOX=-74.1,40.6,-73.9,40.9
&WIDTH=1024
&HEIGHT=1024
&DOSHAPES=TRUE

To generate a raster image from a table flights with the following characteristics:

• The track data is extracted, by default, from the flights table's TRACKID, x, y, & TIMESTAMP columns
• SRS is EPSG:4326
• Bounding box longitude is from -180 to 180 and latitude is from -90 to 90
• Image size is 512 by 512
• Track rendering is enabled
• Track headers are diamond-shaped
• Track line color is set to 80858E
• Track marker color is set to 006BBB
• Track markers are square-shaped

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

${KINETICA_URL}/wms?REQUEST=GetMap
&STYLES=raster
&LAYERS=demo.flights
&SRS=EPSG:4326
&BBOX=-180,-90,180,90
&WIDTH=512
&HEIGHT=512
&DOTRACKS=1
&TRACKHEADSHAPES=diamond
&TRACKLINECOLORS=80858E
&TRACKMARKERCOLORS=006BBB
&TRACKMARKERSHAPES=square

To generate a raster image with the following characteristics using information from a table nyctaxi and symbols generated from a taxi icon SVG file:

• X-axis position is extracted from the nyctaxi table's dropoff_longitude column
• Y-axis position is extracted from the nyctaxi table's dropoff_latitude column
• The symbol attribute is set using a series of if statements:
  • If total_amount is less than or equal to 20 but greater than 10, set the symbol to taxi_green
  • If total_amount is greater than 20, set the symbol to taxi_blue
  • If total_amount is less than 10, set the symbol to taxi_default
• SRS is PLATE_CARREE
• Bounding box longitude is from -73.99120 to -73.99115 and latitude is from 40.750300 to 40.750350
• Image size is 512 by 512
• Symbology rendering is enabled

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

${KINETICA_URL}/wms?REQUEST=GetMap
&STYLES=raster
&LAYERS=demo.nyctaxi
&X_ATTR=dropoff_longitude
&Y_ATTR=dropoff_latitude
&SYMBOL_ATTR=if(total_amount<=20%20and%20total_amount>10,'taxi_green',if(total_amount>20,'taxi_blue','taxi_default'))
&SRS=PLATE_CARREE
&BBOX=-73.99120,40.750300,-73.99115,40.750350
&WIDTH=512
&HEIGHT=512
&DOSYMBOLOGY=TRUE
&TRACKMARKERSHAPES=SYMBOLCODE

1
   2
   3
   4
   

curl -sS -X POST ${KINETICA_URL}/insert/symbol \
   --header "Content-Type: application/json" \
   --user ${USERNAME}:${PASSWORD} \
   --data '{"symbol_id":"taxi_green", "symbol_format":"svg_path", "symbol_data":"'${SVG_PATH}'", "options":{"color":"00FF00"}}'
   

1
   2
   3
   4
   

curl -sS -X POST ${KINETICA_URL}/insert/symbol \
   --header "Content-Type: application/json" \
   --user ${USERNAME}:${PASSWORD} \
   --data '{"symbol_id":"taxi_blue", "symbol_format":"svg_path", "symbol_data":"'${SVG_PATH}'", "options":{"color":"FF0000"}}'
   

1
   2
   3
   4
   

curl -sS -X POST ${KINETICA_URL}/insert/symbol \
   --header "Content-Type: application/json" \
   --user ${USERNAME}:${PASSWORD} \
   --data '{"symbol_id":"taxi_default", "symbol_format":"svg_path", "symbol_data":"'${SVG_PATH}'", "options":{"color":"0000FF"}}'
   

CB_RASTER

The class break raster mode is for generating class break renderings. A class break rendering is the rasterization of the data from one or more tables with styling applied on a per-class basis. Distinct values (for strings) or ranges (for numeric columns) must be provided in the CB_VALS parameter.

0  up to but not including 5
5  up to but not including 10
15 up to but not including 30

0  up to but not including 5
5  up to but not including 10
15 up to but not including 30

0  up to but not including 5
5  up to but not including 10
15 up to but not including 30

0  up to but not including 5
5  up to but not including 10
15 up to but not including 30

0  up to but not including 5
5  up to but not including 10
15 up to but not including 30

All of the RASTER-mode styling parameters are valid for CB_RASTER (except SYMBOLROTATIONS); however, there must be styling parameters specified for each class. Each entry in CB_VALS connotes an individual class to which styling is applied. If styling parameters are not provided for a class, the default value is applied.

The per-style class break parameters (CB_POINTCOLOR..., CB_POINTSIZE..., and CB_POINTSHAPE...) can be used to override attribute color, size, or shapes if the given data falls into the given range, e.g., enlarge a point's size if its total sales amount was greater than some amount.

The keyword <other> can be used as a value in CB_VALS instead of a class name to render all non-matching classes as specified by corresponding style options. The length of the style options must match the number of classes specified (including <other>).

For example, to generate a category-based class-break raster image from a table nyctaxi with the following characteristics:

• X-axis position is extracted from the nyctaxi table's pickup_longitude column
• Y-axis position is extracted from the nyctaxi table's pickup_latitude column
• Passenger count is extracted from the nyctaxi table's passenger_count column
• Classes are:
  1. Between 1 and 2 passengers -- diamonds colored yellow (999900)
  2. Between 3 and 5 passengers -- circles colored orange (CC6600)
  3. Anything else (as designated by the <other> keyword) -- squares colored red (FF0000)
• SRS is PLATE_CARREE
• Bounding box longitude is from -74.1 to -73.9 and latitude is from 40.6 to 40.9
• Image size is 1024 x 1024
• ORDER_CLASSES is enabled, so 999900 will be rendered first, CC6600 will be rendered below that, and FF0000 below that
• Points have a size of 2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

${KINETICA_URL}/wms?REQUEST=GetMap
&STYLES=cb_raster
&LAYERS=demo.nyctaxi
&X_ATTR=pickup_longitude
&Y_ATTR=pickup_latitude
&CB_ATTR=passenger_count
&CB_VALS=1:3,3:5,<other>
&POINTCOLORS=999900,CC6600,FF0000
&POINTSHAPES=diamond,circle,square
&SRS=PLATE_CARREE
&BBOX=-74.1,40.6,-73.9,40.9
&WIDTH=1024
&HEIGHT=1024
&ORDER_CLASSES=true
&POINTSIZES=2

HEATMAP

The heatmap mode is used to generate a heat map image of one or more tables. Heatmaps are a visual representation of the information contained in the given tables.

Available parameters are:

For the Heatmap mode in particular, the BBOX parameter defines the geographic area while the WIDTH and HEIGHT parameters define the pixel grid resolution over which the heatmap will be calculated.

If COLORMAP is specified, it will be used regardless of whether GRADIENT_START_COLOR/GRADIENT_END_COLOR are specified. If the given colormap is invalid, an error will be returned. If COLORMAP is blank or unspecified, GRADIENT_START_COLOR/GRADIENT_END_COLOR are used, if specified. If none of these is specified, the jet colormap will be used.

VAL_ATTR can be used to enable special behaviors. A description of the behavior as well as how to enable the behavior can be found below.

• Count - the number of records at each pixel is used to generate the heatmap
  • If no VAL_ATTR is specified or VAL_ATTR=
  • VAL_ATTR=count(column_name)
• Sum - the sum of column_name within each pixel is used to generate the heatmap
  • VAL_ATTR=column_name
  • VAL_ATTR=sum(column_name)
• Average - the average of column_name within each pixel is used to generate the heatmap
  • VAL_ATTR=avg(column_name)
  • VAL_ATTR=mean(column_name)
• Minimum - the minimum of column_name within each pixel is used to generate the heatmap
  • VAL_ATTR=min(column_name)
• Maximum - the maximum of column_name within each pixel is used to generate the heatmap
  • VAL_ATTR=max(column_name)

In addition the log function can be applied within VAL_ATTR. This can be helpful when the data values span a very large range. To apply this, wrap the VAL_ATTR with log. For example:

• VAL_ATTR=log(sum(column_name))
• VAL_ATTR=log(avg(column_name))
• VAL_ATTR=log(min(column_name))
• VAL_ATTR=log(max(column_name))

For example, to generate a heatmap image from a table nyctaxi with the following characteristics:

• X-axis position is extracted from the nyctaxi table's pickup_longitude column
• Y-axis position is extracted from the nyctaxi table's pickup_latitude column
• SRS is PLATE_CARREE
• Bounding box longitude is from -80 to -70 and latitude is from 35 to 45
• Image size is 512 x 512
• A blur radius of 5
• A plasma colormap

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

${KINETICA_URL}/wms?REQUEST=GetMap
&STYLES=heatmap
&LAYERS=demo.nyctaxi
&X_ATTR=pickup_longitude
&Y_ATTR=pickup_latitude
&SRS=PLATE_CARREE
&BBOX=-80,35,-70,45
&WIDTH=512
&HEIGHT=512
&BLUR_RADIUS=5
&COLORMAP=plasma

CONTOUR

The contour mode is used to generate a contour plot image of one or more tables. A contour plot is a plane section of the three-dimensional graph of the function z = f(x, y) parallel to the x, y plane. Contour plots contain isolines, which show the location(s) where the data has the same z value.

Available parameters are:

To be able to construct a contour plot, we first need to grid the data in a regularly-spaced XY array. This is achieved using the GRIDDING_METHOD parameter, which is the most influential parameter of the contour plot. The GRIDDING_METHOD determines how the data is interpolated/extrapolated and will also impact the speed at which the plot can be generated. The only method supported at this time is INV_DST_POW (Inverse Distance to a Power), though GRIDDING_METHOD is a required parameter.

The SEARCH_RADIUS heavily influences both the quality and speed of the contour plot. It is method dependent and should be adjusted based on the quantity and quality of the input data.

Once the grid is obtained, a marching squares algorithm is used to obtain the isolines. The grid can be visualized by setting RENDER_OUTPUT_GRID to 1 (true).

Additionally, we can set ADJUST_GRID to 1 (true) if the density of the data in the current viewport is so low that the resulting grid is not filled properly when using the user-specified grid size and search radius. This option will automatically adapt the grid size and/or search radius to get a better interpolation of the data by first running a coarse gridding pass, then collecting data about density and sparsity, and finally choosing the latter value accordingly before re-running the contour lines generation.

Finally, labels can be added to the isolines by setting ADD_LABELS to true. Label font size, font family, angle, and separation are the main parameters to control how the labels are displayed.

For example, to generate a contour plot image from a table nyctaxi, first aggregate the taxi trip data, counting the number dropoffs at the same location:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

curl -sS -X POST ${KINETICA_URL}/aggregate/groupby \
--header "Content-Type: application/json" \
--user ${USERNAME}:${PASSWORD} \
--data @- <<PARAMS
{
  "table_name": "demo.nyctaxi",
  "column_names": ["dropoff_longitude", "dropoff_latitude", "float(count(*)) as dropoff_point_count"],
  "offset":0,
  "limit":-9999,
  "encoding":"json",
  "options": {"result_table":"contour_source", "expression":"dropoff_latitude > 0", "having":"count(*) > 1"}
}
PARAMS

Then, generate the contour plot from the contour_source table using the number of dropoffs at a given location as the "z" axis for the contour, and the following additional characteristics:

• X-axis position is extracted from the contour_source table's dropoff_longitude column
• Y-axis position is extracted from the contour_source table's dropoff_latitude column
• Z value for the contour plot isolines is extracted from the contour_source table's dropoff_point_count column
• SRS is PLATE_CARREE
• Bounding box longitude is from -75 to -73 and latitude is from 40 to 42
• Image size is 512 x 512
• Labels are added; labels of different values are separated by a space worth 5 times the font size (default font size is 12)
• Grid size and search radius are automatically adjusted based on the viewport
• A terrain colormap
• Grid cell width is 100 times smaller than the image width
• Number of individually-separated isolines is set to 50
• Search radius for the isolines is 15% of the grid
• Minimum & maximum isoline level values are automatically adjusted based on the viewport (default)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

${KINETICA_URL}/wms?REQUEST=GetMap
&STYLES=contour
&LAYERS=contour_source
&X_ATTR=dropoff_longitude
&Y_ATTR=dropoff_latitude
&VAL_ATTR=dropoff_point_count
&GRIDDING_METHOD=INV_DST_POW
&SRS=PLATE_CARREE
&BBOX=-75,40,-73,42
&WIDTH=512
&HEIGHT=512
&FORMAT=image/png
&ADD_LABELS=1
&ADJUST_GRID=1
&COLORMAP=terrain
&GRID_SIZE=100
&LABELS_INTRALEVEL_SEPARATION=5
&NUM_LEVELS=50
&SEARCH_RADIUS=15

LABELS

The labels mode is used to show labels on the map rather than points. Available parameters are:

All LABELS parameters can use expressions. To read more about the different types of expressions, see expressions. Strings inside expressions must be enclosed in single or double quotes. Expressions inside the LABEL_TEXT_COLOR, LABEL_LINE_COLOR, and LABEL_FILL_COLOR parameters must resolve to 6 or 8 hex digits or the color won't work. Note that if the expression resolves to 6 hex digits, an alpha value of FF is automatically added.

To use labels, the requested TrueType fonts must be loaded on all servers in the Kinetica cluster, in the /usr/share/fonts directory. Kinetica must be restarted to see any new fonts placed in this directory.

Labels and shapes cannot be rendered in the same WMS call. Both can be shown on the same map by creating separate map layers, each with its own WMS call. When making the WMS call for the labels to be generated, the LAYERS parameter (geospatial source table containing the shapes) can be left blank.

LABEL_DRAW_BOX and LABEL_DRAW_LEADER will only take values that are castable to boolean values (e.g., 1 and 0). "TRUE" and "FALSE" are not valid.

All colors must be provided in hex notation in the format RRGGBB or AARRGGBB (to specify the alpha value). For example, partially transparent red may be given as B3FF0000.

Parameters other than the following can be either literals of the appropriate parameter type or column names containing values of the appropriate type:

• LABEL_LAYER
• LABEL_X_ATTR
• LABEL_Y_ATTR
• LABEL_LEADER_X_ATTR
• LABEL_LEADER_Y_ATTR

For example, to generate a label image overlay from a table nyctaxi with the following characteristics:

• X-axis position is extracted from the nyctaxi table's dropoff_longitude column
• Y-axis position is extracted from the nyctaxi table's dropoff_latitude column
• Labels are only drawn for dropoff points where the passenger count was greater than 5
• SRS is EPSG:4326
• Bounding box longitude is from -74.1 to -73.9 and latitude is from 40.6 to 40.9
• Image size is 512 x 512
• A blue-filled (B3006BBB) box is drawn around each label
• Label text is dropoff, is white (FFFFFF), scaled to 40% smaller (0.6 x) than normal, rotated 15 degrees clockwise

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

${KINETICA_URL}/wms?REQUEST=GetMap
&STYLES=labels
&LABEL_LAYER=demo.nyctaxi
&LABEL_X_ATTR=dropoff_longitude
&LABEL_Y_ATTR=dropoff_latitude
&LABEL_FILTER=passenger_count>5
&SRS=EPSG:4326
&BBOX=-74.1,40.6,-73.9,40.9
&WIDTH=512
&HEIGHT=512
&LABEL_DRAW_BOX=1
&LABEL_FILL_COLOR=B3006BBB
&LABEL_TEXT_ANGLE=15
&LABEL_TEXT_COLOR=FFFFFF
&LABEL_TEXT_STRING='dropoff'
&LABEL_TEXT_SCALE=0.6

ISOCHRONES

The isochrones mode is used to generate an image containing isolines for travel results using an existing graph. Isolines represent curves of equal cost, with cost typically referring to the time or distance assigned as the weights of the underlying graph.

Available parameters are: