/wms

URL: http://GPUDB_IP_ADDRESS:GPUDB_PORT/wms

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.

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

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)
POINTSHAPES	Shape of points	none circle square diamond hollowcircle hollowsquare hollowdiamond SYMBOLCODE (to specify a symbol)
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)
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

In addition, 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 a 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
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

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	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	TRUE or FALSE	FALSE
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	TRUE or FALSE	FALSE
LABEL_LINE_WIDTH	width of line for box & leader line	Number	1
LABEL_LINE_COLOR	color of line for box & leader line	Hex color	FF000000
LABEL_FILL_COLOR	color of fill for box	Hex color	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

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.

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.

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=TRUE
   &LABEL_DRAW_LEADER=TRUE
   &LABEL_LINE_WIDTH=2
   &LABEL_LEADER_X_ATTR=leader_x
   &LABEL_LEADER_Y_ATTR=leader_y
   &LABEL_LINE_COLOR=FF990000
   &LABEL_FILL_COLOR=FF000099
   &...

CACHED

The cached mode is intended to be used in conjunction with the /visualize/video endpoint. Once the endpoint has been called, the generated video frames are available for download via WMS using STYLES=cached. In this case, the LAYERS parameter should be populated with the session key passed in to /visualize/video and the FRAME parameter indicates which 0-based frame of the video should be returned. All other WMS parameters are ignored for this mode.

For instance, if a 20 frame video with the session key MY-SESSION-KEY was generated with a call to /visualize/video, the first frame could be retrieved with the URL:

http://<host>:9191/wms
   ?REQUEST=GetMap
   &STYLES=cached
   &LAYERS=MY-SESSION-KEY
   &FRAME=0

and the last frame could be retrieved with:

http://<host>:9191/wms
   ?REQUEST=GetMap
   &STYLES=cached
   &LAYERS=MY-SESSION-KEY
   &FRAME=19