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`
`HASHLINEANGLES`	Clockwise rotation angle from a perpedicular hash line in degree.	Real numbers	`0`
`HASHLINECOLORS`	RBG color values in hex for the hash lines	Hex color (or `-1` for same color as shapeline)	`SHAPELINECOLOR` value
`HASHLINEINTERVALS`	Distance between the center points of hash lines in pixels	Positive integers	`20`
`HASHLINELENS`	Length of hash lines in pixels. Inputting a `0` disables hash lines	Non-negative integers	`0`
`HASHLINEWIDTHS`	Width of hash lines in pixels	Positive integers	`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)
`POINTSIZES`	Size of points	`0` - `20`	`3`
`SHAPEFILLCOLORS`	Fill color for closed shapes (i.e. polygons)	Hex color (or `-1` for no fill)	`-1` (no fill)
`SHAPELINECOLORS`	Line colors for shapes	Hex color	`FFFF00` (yellow)
`SHAPELINEPATTERNLENS`	Lengths of dashed-line patterns in number of bits	`1` - `64`	`0`
`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`
`SHAPELINEWIDTHS`	Line widths of shapes	`0` - `20`	`3`
`SYMBOLROTATIONS`	Angle in degree for clockwise symbol rotation	Numeric constants or expressions (including column names)
`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`
`TRACKHEADSIZES`	Size of track head markers	`0` - `20`	`10`
`TRACKLINECOLORS`	Line colors for tracks	Hex color	`00FF00` (green)
`TRACKLINEWIDTHS`	Line widths of tracks	`0` - `20` (`0`: don't draw the track lines)	`3`
`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`
`TRACKMARKERSIZES`	Size of track point markers	`0` - `20`	`2`

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 CB_VALS parameter.

Important

All RASTER mode parameters except SYMBOLROTATIONS can be used with the CB_RASTER mode in addition to the parameters listed below

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:

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

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 a value in a list of classes 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, 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 ( 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.

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
   &...

Table Of Contents

Web Map Service¶

Overview¶

Required Parameters¶

Optional Parameters¶

Modes¶

RASTER¶

CB_RASTER¶

HEATMAP¶

LABELS¶