Version:

Web Map Service

Overview

Kinetica provides a Web Map Service (WMS) for generating image tiles from the geospatial data contained in it. The type of image tiles returned, the data used to generate the tiles, and the graphical styles in the tiles are specified in the query string of the WMS call. These would typically be used as overlays on top of a map. Examples of this can be seen in the demo that comes bundled with Kinetica at http://<host>:8080/gaiademo. Any table with x,y coordinates or WKT shapes can be used as the source for generating images.

Note that the cb_raster and raster styles have a GEO_ATTR parameter that allows specifying the name of a geometry (WKT) column to use during rendering. This parameter is optional as Kinetica will automatically find a geometry column, but if there's multiple geometry columns and a specific column needs to be used, GEO_ATTR is necessary. If the specified GEO_ATTR column exists and is a geometry-type column, Kinetica will continue with rendering. If the column does not exist or it is not a geometry-type column, Kinetica will try to process the column as point or track data instead.

Important

If GEO_ATTR is not specified and there's more than one geometry column, Kinetica will attempt to process the columns as point or track data.

A typical Kinetica WMS request would look like:

http://<host>:9191/wms
   ?REQUEST=GetMap
   &STYLES=raster
   &SRS=EPSG:4326
   &WIDTH=1024
   &HEIGHT=1024
   &LAYERS=MASTER

The requested image is then returned in the HTTP response message body.

Required Parameters

The following parameters are required in all WMS calls:

Name Description Allowable Values
REQUEST WMS Request
  • GetMap for getting an image
  • GetCapabilities is also supported
SRS Spatial Reference System (i.e. EPSG code)
  • Plate Carree projection codes: PLATE_CARREE, EPSG:4326
  • Web Mercator projection codes: WEB_MERCATOR, 900913, EPSG:900913, 102100, EPSG:102100, 3857, EPSG:3857
LAYERS The requested image layer(s) One or more comma-separated table names
BBOX Geographic bounding box as a comma-separated list of: min_longitude, min_latitude, max_longitude, max_latitude Four comma-separated numerics
WIDTH Image width, in pixels; best performance if a power of 2 64 - 8192
HEIGHT Image height, in pixels; best performance if a power of 2 64 - 8192

Optional Parameters

The following parameters are optional for WMS calls:

Name Description Allowable Values Default Value
VERSION WMS Version--only v1.1.1 is supported 1.1.1 1.1.1
STYLES The mode of image requested
  • raster
  • cb_raster
  • heatmap
  • labels
  • cached
raster
FORMAT Output image format--only PNG is supported image/png image/png
TRANSPARENT Controls background transparency of the generated image
  • TRUE for transparent background
  • FALSE for opaque background
TRUE
X_ATTR Name of the column to be used as the longitude Numeric column from LAYERS source table list Column x
Y_ATTR Name of the column to be used as the latitude Numeric column from LAYERS source table list Column y
GEO_ATTR The WKT attribute used to render the raster/cb_raster (particularly if you have more than one WKT column in the table) A WKT column name  

Modes

The following modes are supported, as specified by the STYLES parameter:

  • raster
  • cb_raster
  • heatmap
  • labels
  • cached

Descriptions of each mode along with the mode-specific parameters can be found below.

RASTER

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

Name Description Allowable Values Default Value
DOPOINTS Rasterize point data toggle TRUE or FALSE TRUE
DOSHAPES Rasterize shapes toggle TRUE or FALSE TRUE
DOSYMBOLOGY Rasterize symbols toggle TRUE or FALSE FALSE
DOTRACKS Rasterize tracks TRUE or FALSE TRUE
POINTSIZES Size of points 0 - 20 3
POINTCOLORS Color of points Hex color FF0000 (red)
POINTOFFSET_X Horizontal offset for point location in pixels. Signed integers 0
POINTOFFSET_Y Vertical offset for point location in pixels. Signed integers 0
POINTSHAPES Shape of points
  • none
  • circle
  • square
  • diamond
  • hollowcircle
  • hollowsquare
  • hollowdiamond
  • SYMBOLCODE (to specify a symbol)
 
SHAPELINEPATTERNS Bitmaps representing dashed-line patterns. Bits of 1 enable the pixels associated with them, but if all bits are 0, dashed-line drawing is disabled, i.e. solid lines are drawn Unsigned 64-bit (hexadecimal) integers 0
SHAPELINEPATTERNLENS Lengths of dashed-line patterns in number of bits Unsigned 64-bit (hexadecimal) integers 0
SHAPELINEWIDTHS Line widths of shapes 0 - 20 3
SHAPELINECOLORS Line colors for shapes Hex color FFFF00 (yellow)
SHAPEFILLCOLORS Fill color for closed shapes (i.e. polygons) Hex color (or -1 for no fill) -1 (no fill)
SYMBOLROTATIONS Angle in degree for clockwise symbol rotation Numeric constants or expressions (including column names)  
TRACKLINEWIDTHS Line widths of tracks 0 - 20 (0: don't draw the track lines) 3
TRACKLINECOLORS Line colors for tracks Hex color 00FF00 (green)
TRACKMARKERSIZES Size of track point markers 0 - 20 2
TRACKMARKERCOLORS Color of track point markers Hex color 0000FF (blue)
TRACKMARKERSHAPES Shape of track point markers
  • none
  • circle
  • square
  • diamond
  • hollowcircle
  • hollowsquare
  • hollowdiamond
  • SYMBOLCODE (to specify a symbol)
none
TRACKHEADSIZES Size of track head markers 0 - 20 10
TRACKHEADCOLORS Color of track head markers Hex color FFFFFF (white)
TRACKHEADSHAPES Shape of track head markers
  • none
  • circle
  • square
  • diamond
  • hollowcircle
  • hollowsquare
  • hollowdiamond
  • SYMBOLCODE (to specify a symbol)
circle

Important

The WORLDLAYERS parameter can be used if the table(s) specified in the LAYERS parameter only have a subset of all track points and the desired behavior is to render the entire track. In this case the unique track ids existing in the LAYERS table(s) will be identified, but the actual track points will be pulled from the WORLDLAYERS table(s).

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.

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 an unrestricted string type column named SYMBOLCODE, which is 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.

Note: 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.

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

  • SRS is EPSG:4326
  • X-axis position is extracted from the Geo table's pos_x column
  • Y-axis position is extracted from the Geo table's pos_y column
  • Image size is 768 x 512
  • Bounding box latitude is from -90 to 90 and longitude is from -180 to 180
  • A point size of 5 and color of purple (990099)
http://<host>:9191/wms
   ?REQUEST=GetMap
   &SRS=EPSG:4326
   &WIDTH=768
   &HEIGHT=512
   &LAYERS=Geo
   &BBOX=-180,-90,180,90
   &X_ATTR=pos_x
   &Y_ATTR=pos_y
   &POINTSIZES=5
   &POINTCOLORS=990099

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 values parameter. In addition to all of the RASTER mode parameters, the additional parameters for this mode are:

Name Description Allowable Values
CB_ATTR Class break attribute (Required) Any column from LAYERS source table list
CB_VALS

Values or ranges to apply for the class break (Required)

NOTE: The starting value of the range is inclusive and the end value is exclusive

Comma separated list of values or ranges (e.g., 0:5,5:10,15:30)

This specifies three ranges:

0  up to but not including 5
5  up to but not including 10
15 up to but not including 30
POINTOFFSET_X Horizontal offset for point location in pixels. Signed integers
POINTOFFSET_Y Vertical offset for point location in pixels. Signed integers
SHAPELINEPATTERNS Bitmaps representing dashed-line patterns. Bits of 1 enable the pixels associated with them, but if all bits are 0, dashed-line drawing is disabled, i.e. solid lines are drawn Unsigned 64-bit (hexadecimal) integers
SHAPELINEPATTERNLENS Lengths of dashed-line patterns in number of bits Unsigned 64-bit (hexadecimal) integers
USE_POINT_RENDERER

Set to true for points larger than 1 pixel.

NOTE: If unset, or false, all points will be one pixel

true or false

The keyword <other> can be used as the last value in a list of classes instead of a class name. This keyword will 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, using <other> below would match the areas that don't match with the range 0:10000

http://<host>:9191/wms
   ?REQUEST=GetMap
   &STYLES=cb_raster
   &SRS=PLATE_CARREE
   &WIDTH=768
   &HEIGHT=512
   &LAYERS=Geo
   &BBOX=-180,-90,180,90
   &X_ATTR=pos_x
   &Y_ATTR=pos_y
   &CB_ATTR=pop_density
   &CB_VALS=0:10000,<other>
   &POINTCOLORS=999900,FF0000

All of the RASTER-mode styling parameters are valid for CB_RASTER; however, there must be styling parameters specified for each class. Each entry in CB_VALS connotes an individual class to which styling is applied.

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

  • X-axis position is extracted from the Geo table's pos_x column
  • Y-axis position is extracted from the Geo table's pos_y column
  • Image size is 768 x 512
  • Bounding box latitude is from -90 to 90 and longitude is from -180 to 180
  • Location population density is extracted from the Geo table's pop_density column
  • Locations with Sparse, Average, and Dense population densities are colored yellow (999900), orange (CC6600), and red (FF0000), respectively
http://<host>:9191/wms
   ?REQUEST=GetMap
   &STYLES=cb_raster
   &SRS=PLATE_CARREE
   &WIDTH=768
   &HEIGHT=512
   &LAYERS=Geo
   &BBOX=-180,-90,180,90
   &X_ATTR=pos_x
   &Y_ATTR=pos_y
   &CB_ATTR=pop_density
   &CB_VALS=Sparse,Average,Dense
   &POINTCOLORS=999900,CC6600,FF0000

To generate a range-based class-break raster image from a table Geo with the following characteristics:

  • X-axis position is extracted from the Geo table's pos_x column
  • Y-axis position is extracted from the Geo table's pos_y column
  • Image size is 768 x 512
  • Bounding box latitude is from -90 to 90 and longitude is from -180 to 180
  • Location population is extracted from the Geo table's population column
  • Locations with populations of 0 - 10,000, 10,001 - 100,000, and 100,001 to 100,000,000 are colored yellow (999900), orange (CC6600), and red (FF0000), respectively
http://<host>:9191/wms
   ?REQUEST=GetMap
   &STYLES=cb_raster
   &SRS=PLATE_CARREE
   &WIDTH=768
   &HEIGHT=512
   &LAYERS=Geo
   &BBOX=-180,-90,180,90
   &X_ATTR=pos_x
   &Y_ATTR=pos_y
   &CB_ATTR=population
   &CB_VALS=0:10000,10001:100000,100001:100000000
   &POINTCOLORS=999900,CC6600,FF0000

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.

Note: Heatmap is only available on CUDA builds

Available parameters are:

Name Description Allowable Values Default Value
BLUR_RADIUS Blurring radius for the heat map 1 - 32 5
COLORMAP Colormap for the heat map
  • Perceptually-Uniform - viridis, inferno, plasma, magma
  • Sequential I - Blues, BuGn, BuPu, GnBu, Greens, Greys, Oranges, OrRd, PuBu, PuBuGn, PuRd, Purples, RdPu, Reds, YlGn, YlGnBu, YlOrBr, YlOrRd
  • Sequential II - afmhot, autumn, bone, cool, copper, gist_heat, gray, gist_gray, gist_yarg, binary, hot, pink, spring, summer, winter
  • Diverging - BrBG, bwr, coolwarm, PiYG, PRGn, PuOr, RdBu, RdGy, RdYlBu, RdYlGn, Spectral, seismic
  • Qualitative - Accent, Dark2, Paired, Pastel1, Pastel2, Set1, Set2, Set3
  • Misc - gist_earth, terrain, ocean, gist_stern, brg, CMRmap, cubehelix, gnuplot, gnuplot2, gist_ncar, spectral, nipy_spectral, jet, rainbow, gist_rainbow, hsv, flag, prism
jet
GRADIENT_START_COLOR Gradient start color for the heat map Hex color 000000 (black)
GRADIENT_END_COLOR Gradient end color for the heat map Hex color 000000 (black)
VAL_ATTR Attribute to use to calculate the data points for the heat map Any valid column name; can invoke several "behaviors". See below for more information (none)

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)

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

  • X-axis position is extracted from the Geo table's pos_x column
  • Y-axis position is extracted from the Geo table's pos_y column
  • Image size is 768 x 512
  • Bounding box latitude is from -90 to 90 and longitude is from -180 to 180
  • A plasma colormap
http://<host>:9191/wms
   ?REQUEST=GetMap
   &STYLES=heatmap
   &SRS=PLATE_CARREE
   &WIDTH=768
   &HEIGHT=512
   &LAYERS=Geo
   &BBOX=-180,-90,180,90
   &X_ATTR=pos_x
   &Y_ATTR=pos_y
   &COLORMAP=plasma

LABELS

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

Name Description Allowable Values Default Value
LABEL_LAYER name of table to render   N/A - Required
LABEL_X_ATTR name of column containing label's position on the x-axis   Column x
LABEL_Y_ATTR name of column containing label's position on the y-axis   Column y
LABEL_TEXT_STRING text of label to render All printable characters no text
LABEL_FONT font in the format of Name Style(s) Size (e.g. Arial Bold 8) Any font codes available on all database servers default server font
LABEL_TEXT_COLOR text color Hex color (with or without alpha values) or -1 (full transparency) FF000000
LABEL_TEXT_SCALE text scaling factor Number 1
LABEL_TEXT_ANGLE number of degrees clockwise to rotate the label Number 0
LABEL_DRAW_BOX draw a box around the label 0 (false) or 1 (true) 0
LABEL_DRAW_LEADER draw a leader line from each label to its x,y point specified by LABEL_LEADER_X_ATTR & LABEL_LEADER_Y_ATTR columns 0``(false) or ``1 (true) 0
LABEL_LINE_WIDTH width of line for box & leader line Number 1
LABEL_LINE_COLOR color of line for box & leader line Hex color (with or without alpha values) or -1 (full transparency) FF000000
LABEL_FILL_COLOR color of fill for box Hex color (with or without alpha values) or -1 (full transparency) FF000000
LABEL_LEADER_X_ATTR name of column containing leader line's terminating position on the x-axis (the end opposite the label)   N/A
LABEL_LEADER_Y_ATTR name of column containing leader line's terminating position on the y-axis (the end opposite the label)   N/A
LABEL_FILTER boolean expression used to filter which labels are included from LABEL_LAYER.   N/A

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 Geo with the following characteristics:

  • X-axis position is extracted from the Geo table's pos_x column
  • Y-axis position is extracted from the Geo table's pos_y column
  • Text is extracted from the Geo table's label_text column, is a semi-transparent green (99009900), scaled to 20% larger (1.2 x) than normal, rotated 30 degrees clockwise, rendered with the Arial Bold 8 font
  • A 2-width, red-bordered (FF990000), blue-filled (FF000099) box is drawn around each label
  • A 2-width, red (FF990000) leader line is drawn from each label to the corresponding point extracted from the leader_x & leader_y columns from the same record
http://<host>:9191/wms
   ?...
   &STYLES=labels
   &LABEL_LAYER=Geo
   &LABEL_TEXT_STRING=label_text
   &LABEL_FONT=Arial%20Bold%208
   &LABEL_X_ATTR=pos_x
   &LABEL_Y_ATTR=pos_y
   &LABEL_TEXT_COLOR=99009900
   &LABEL_TEXT_SCALE=1.2
   &LABEL_TEXT_ANGLE=30
   &LABEL_DRAW_BOX=1
   &LABEL_DRAW_LEADER=1
   &LABEL_LINE_WIDTH=2
   &LABEL_LEADER_X_ATTR=leader_x
   &LABEL_LEADER_Y_ATTR=leader_y
   &LABEL_LINE_COLOR=FF990000
   &LABEL_FILL_COLOR=FF000099
   &...