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 athttp://<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 or column expression
to use during rendering. This parameter is optional, and if not specified,
Kinetica will automatically try to find a geometry column. If there are
multiple geometry columns to choose from and a specific column needs to be used,
GEO_ATTR will need to be specified. If the GEO_ATTR column reference or
expression corresponds to a valid geometry column or expression, Kinetica will
continue with rendering. If not, Kinetica will try to process the column or
expression as point or track data instead.
The requested image is then returned in the HTTP response message body.
As the isochrones mode utilizes some of the contour and labels modes’
parameters as well as some of the
/solve/graph endpoint’s parameters, the
same usage guidelines apply. Review Contour, Labels, and
Solving a Graph
for more information.
Downloads
The examples below use the following tables:- nyc_neighborhood (referenced in the examples as if it were in the caller’s default schema)
demo.flights(downloadable as flights.csv)demo.nyctaxi(downloadable as nyctaxi.csv)
Usage
Base WMS URI:Required Parameters
The following parameters are required in all WMS calls:Optional Parameters
The following parameters are optional for WMS calls:Modes
The following modes are supported, as specified by theSTYLES parameter:
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:
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:
Labels (using the labels style) and WKT 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.
- The geometry data is extracted from the
nyc_neighborhoodtable’sgeomcolumn - SRS is
EPSG:4326 - Bounding box longitude is from
-74.1to-73.9and latitude is from40.6to40.9 - Image size is
1024x1024 - The raster image will render shapes because
DOSHAPESis set toTRUE
flights with the following
characteristics:
- The track data is extracted, by default, from the
flightstable’sTRACKID,x,y, &TIMESTAMPcolumns - SRS is
EPSG:4326 - Bounding box longitude is from
-180to180and latitude is from-90to90 - Image size is
512by512 - 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
nyctaxi and symbols generated from a taxi icon SVG file:
-
X-axis position is extracted from the
nyctaxitable’sdropoff_longitudecolumn -
Y-axis position is extracted from the
nyctaxitable’sdropoff_latitudecolumn -
The symbol attribute is set using a series of
ifstatements:- If
total_amountis less than or equal to 20 but greater than 10, set the symbol totaxi_green - If
total_amountis greater than 20, set the symbol totaxi_blue - If
total_amountis less than 10, set the symbol totaxi_default
- If
-
SRS is
PLATE_CARREE -
Bounding box longitude is from
-73.99120to-73.99115and latitude is from40.750300to40.750350 -
Image size is
512by512 - Symbology rendering is enabled
The
SYMBOL_ATTR statement above references three symbols: taxi_green,
taxi_blue, and taxi_default. Symbols are created in Kinetica using
an SVG path or raw bytes reprsenting an SVG file via
Insert Symbol. In the example, the symbols are
created using an SVG path extracted from the
taxi.svg file which is then placed
in the SVG_PATH variable.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 theCB_VALS parameter.
All
RASTER mode parameters except SYMBOLROTATIONS and
ORDER_LAYERS can be used with the CB_RASTER mode in
addition to the parameters listed below
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
nyctaxitable’spickup_longitudecolumn -
Y-axis position is extracted from the
nyctaxitable’spickup_latitudecolumn -
Passenger count is extracted from the
nyctaxitable’spassenger_countcolumn -
Classes are:
- Between 1 and 2 passengers —
diamondscolored yellow (999900) - Between 3 and 5 passengers —
circlescolored orange (CC6600) - Anything else (as designated by the
<other>keyword) —squarescolored red (FF0000)
- Between 1 and 2 passengers —
-
SRS is
PLATE_CARREE -
Bounding box longitude is from
-74.1to-73.9and latitude is from40.6to40.9 -
Image size is
1024x1024 -
ORDER_CLASSESis enabled, so999900will be rendered first,CC6600will be rendered below that, andFF0000below that -
Points have a size of
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_ATTRis specified orVAL_ATTR= VAL_ATTR=count(column_name)
- If no
-
Sum - the sum of column_name within each pixel is used to generate the
heatmap
VAL_ATTR=column_nameVAL_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)
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))
nyctaxi with the
following characteristics:
- X-axis position is extracted from the
nyctaxitable’spickup_longitudecolumn - Y-axis position is extracted from the
nyctaxitable’spickup_latitudecolumn - SRS is
PLATE_CARREE - Bounding box longitude is from
-80to-70and latitude is from35to45 - Image size is
512x512 - A blur radius of
5 - A plasma colormap
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 functionz = 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.
Contour mode only supports direct column references for
X_ATTR,
Y_ATTR, & VAL_ATTR parameters; column expressions are not
supported.
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:
This result filters out bad GPS data with a 0,0 location and limits
the data set to locations where more than one dropoff occurred. It stores
the results in a table named
contour_source.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_sourcetable’sdropoff_longitudecolumn - Y-axis position is extracted from the
contour_sourcetable’sdropoff_latitudecolumn - Z value for the contour plot isolines is extracted from the
contour_sourcetable’sdropoff_point_countcolumn - SRS is
PLATE_CARREE - Bounding box longitude is from
-75to-73and latitude is from40to42 - Image size is
512x512 - Labels are added; labels of different values are separated by a space worth
5times the font size (default font size is12) - Grid size and search radius are automatically adjusted based on the viewport
- A terrain colormap
- Grid cell width is
100times 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)
LABELS
The labels mode is used to show labels on the map rather than points. Available parameters are:When using the labels mode,
LABEL_LAYER is required.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_LAYERLABEL_X_ATTRLABEL_Y_ATTRLABEL_LEADER_X_ATTRLABEL_LEADER_Y_ATTR
nyctaxi with the
following characteristics:
- X-axis position is extracted from the
nyctaxitable’sdropoff_longitudecolumn - Y-axis position is extracted from the
nyctaxitable’sdropoff_latitudecolumn - 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.1to-73.9and latitude is from40.6to40.9 - Image size is
512x512 - A blue-filled (
B3006BBB) box is drawn around each label - Label text is
dropoff, is white (FFFFFF), scaled to 40% smaller (0.6x) than normal, rotated15degrees clockwise