/wms

URL: http://<db.host>:<db.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.

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:

Required Parameters

The following parameters are required in all WMS calls:

NameDescriptionAllowable Values
REQUESTWMS Request
  • GetMap for getting an image
  • GetCapabilities is also supported
SRSSpatial 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
LAYERSThe requested image layer(s)One or more comma-separated table names, each in [schema_name.]table_name format, using standard name resolution rules
BBOXGeographic bounding box as a comma-separated list of: min_longitude, min_latitude, max_longitude, max_latitudeFour comma-separated numerics
WIDTHImage width, in pixels; best performance if a power of 264 - 8192
HEIGHTImage height, in pixels; best performance if a power of 264 - 8192

Optional Parameters

The following parameters are optional for WMS calls:

NameDescriptionAllowable ValuesDefault Value
VERSIONWMS Version--only v1.1.1 is supported1.1.11.1.1
STYLESThe mode of image requested
  • raster
  • cb_raster
  • heatmap
  • contour
  • labels
  • isochrones
raster
FORMATOutput image format--only PNG is supportedimage/pngimage/png
TRANSPARENTControls background transparency of the generated image
  • TRUE for transparent background
  • FALSE for opaque background
TRUE
X_ATTRName of the column or expression to be used as the longitudeNumeric column or column expression referencing the LAYERS source table list; must be of int, double, float, or long typeColumn x
Y_ATTRName of the column or expression to be used as the latitudeNumeric column or column expression referencing the LAYERS source table list; must be of int, double, float, or long typeColumn y
GEO_ATTRThe WKT column or expression used to render the raster/cb_raster (particularly if you have more than one WKT column in the table)A WKT column name or expression 
SYMBOL_ATTRThe symbol attribute used to render symbols in lieu of the default SYMBOLCODE column. See DOSYMBOLOGY. Supports expressions, e.g., if(), case(), etc.A string column or expression containing symbol IDsColumn SYMBOLCODE
JOB_USER_DATAUser-defined tag that will be associated with this requestString value not containing '&' 

Modes

The following modes are supported, as specified by the STYLES 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:

NameDescriptionAllowable ValuesDefault Value
ANTIALIASINGSet to TRUE to enable anti-aliasing, which will smoothen WKT LINESTRING and POLYGON outlinesTRUE or FALSEFALSE
DOPOINTSRasterize point data toggleTRUE or FALSETRUE
DOSHAPESRasterize shapes toggleTRUE or FALSETRUE
DOSYMBOLOGYRasterize symbols toggle. When set to TRUE, Kinetica will automatically look for a SYMBOLCODE column in the specified table that contains strings that match inserted symbolsTRUE or FALSEFALSE
DOTRACKSRasterize tracksTRUE or FALSETRUE
HASHLINEANGLESClockwise rotation angle from a perpendicular hash line in degreeReal numbers0
HASHLINECOLORSRBG color values in hex for the hash linesHex color (or -1 for same color as shapeline)SHAPELINECOLOR value
HASHLINEINTERVALSDistance between the center points of hash lines in pixelsPositive integers20
HASHLINELENSLength of hash lines in pixels. Inputting a 0 disables hash linesNon-negative integers0
HASHLINEWIDTHSWidth of hash lines in pixelsPositive integers3
ORDER_LAYERSEnables layers to be rendered in the order they were specified intrue or false 
POINTCOLORSColor of pointsHex colorFF0000 (red)
POINTOFFSET_XHorizontal offset for point location in pixelsSigned integers0
POINTOFFSET_YVertical offset for point location in pixelsSigned integers0
POINTSHAPESShape of points
  • none
  • circle
  • dash
  • diamond
  • dot
  • hollowcircle
  • hollowdiamond
  • hollowsquare
  • hollowsquarewithplus
  • pipe
  • plus
  • square
 
POINTSIZESSize of points0 - 203
SHAPEFILLCOLORSFill color for closed shapes (i.e. polygons)Hex color (or -1 for no fill)-1 (no fill)
SHAPELINECOLORSLine colors for shapesHex colorFFFF00 (yellow)
SHAPELINEPATTERNLENSLengths of dashed-line patterns in number of bits1 - 640
SHAPELINEPATTERNSBitmaps 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 drawnUnsigned 64-bit (hexadecimal) integers0
SHAPELINEWIDTHSLine widths of shapes0 - 203
SYMBOLROTATIONSAngle in degree for clockwise symbol rotationNumeric constants or expressions (including column names) 
TRACKHEADCOLORSColor of track head markersHex colorFFFFFF (white)
TRACKHEADSHAPESShape of track head markers
  • none
  • circle
  • dash
  • diamond
  • dot
  • hollowcircle
  • hollowdiamond
  • hollowsquare
  • hollowsquarewithplus
  • pipe
  • plus
  • square
circle
TRACKHEADSIZESSize of track head markers0 - 2010
TRACKLINECOLORSLine colors for tracksHex color00FF00 (green)
TRACKLINEWIDTHSLine widths of tracks0 - 20 (0: don't draw the track lines)3
TRACKMARKERCOLORSColor of track point markersHex color0000FF (blue)
TRACKMARKERSHAPESShape of track point markers
  • none
  • circle
  • dash
  • diamond
  • dot
  • hollowcircle
  • hollowdiamond
  • hollowsquare
  • hollowsquarewithplus
  • pipe
  • plus
  • square
  • SYMBOLCODE (to specify a symbol)
none
TRACKMARKERSIZESSize of track point markers0 - 202
TRACK_ID_ATTRName of the track ID column or expressionColumn or column expression referencing the LAYERS source table list; must be of string or date typeTRACKID
TRACK_ORDER_ATTRName of the track ordering column or expressionColumn or column expression referencing the LAYERS source table list; must be of numeric or date typeTIMESTAMP
WORLDLAYERS

Supplemental track layer(s); actual points will be pulled from the WORLDLAYERS table(s), though only the unique track IDs in the LAYERS table(s) will be identified on the map.

Ideally, the WORLDLAYERS table(s) should be a superset of the data in the LAYERS table(s).

One or more comma-separated table names, each in [schema_name.]table_name format, using standard name resolution rules 

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')

Note

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.

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

Important

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.

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.

Important

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

NameDescriptionAllowable ValuesDefault Value
CB_ATTRClass break attributeAny column or column expression referencing the LAYERS source table list<Required>
CB_VALS

Values or ranges to apply for the class break

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

List of values or ranges separated by CB_DELIMITER (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
<Required>
CB_DELIMITERA group of characters which separate values or ranges in CB_VALS.Alpha-numeric or special characters,
ORDER_CLASSESEnables classes to be rendered in the order they were specifiedTRUE or FALSEFALSE
USE_POINT_RENDERER

Set to TRUE to render points larger than 1 pixel; if FALSE, all points will be 1 pixel.

NOTE: Only used when OpenGL rendering is disabled

TRUE or FALSEFALSE
CB_POINTALPHA_ATTRClass break attribute applied to only the point alpha.Any column or column expression referencing the LAYERS source table list 
CB_POINTALPHA_VALS

Values or ranges to apply for the CB_POINTALPHA_ATTR class break

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

List of values or ranges separated by CB_DELIMITER (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
 
CB_POINTALPHASComma-separated list of alpha (opacity) in the range 0-255 apply to each class defined by CB_POINTALPHA_VALS. Use 0 for transparent and 255 for opaqueComma-separated list of values in the range 0-255 
CB_POINTCOLOR_ATTRClass break attribute applied to only the point color. Overrides CB_ATTR when appliedAny column or column expression referencing the LAYERS source table list 
CB_POINTCOLOR_VALS

Values or ranges to apply for the CB_POINTCOLOR_ATTR class break

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

List of values or ranges separated by CB_DELIMITER (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
 
CB_POINTSIZE_ATTRClass break attribute applied to only the point size. Overrides CB_ATTR when appliedAny column or column expression referencing the LAYERS source table list 
CB_POINTSIZE_VALS

Values or ranges to apply for the CB_POINTSIZE_ATTR class break

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

List of values or ranges separated by CB_DELIMITER (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
 
CB_POINTSHAPE_ATTRClass break attribute applied to only the point shape. Overrides CB_ATTR when appliedAny column or column expression referencing the LAYERS source table list 
CB_POINTSHAPE_VALS

Values or ranges to apply for the CB_POINTSHAPE_ATTR class break

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

List of values or ranges separated by CB_DELIMITER (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
 
ALPHA_BLENDINGSet to TRUE to enable alpha blending of semi-transparent colors for better rendering of colors when ORDER_CLASSES is set to TRUE. When enabled, alpha blending may affect performance.TRUE or FALSEFALSE
TRACK_ID_ATTRName of the track id columnColumn or column expression referencing the LAYERS source table list; must be of string or date typeTRACKID
TRACK_ORDER_ATTRName of the track ordering columnColumn or column expression referencing the LAYERS source table list; must be of numeric or date typeTIMESTAMP

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:

NameDescriptionAllowable ValuesDefault Value
VAL_ATTRAttribute to use to calculate the data points for the heat map

Column or expression referencing the LAYERS source table list; must be of int, double, float, long, or decimal type. Can invoke several "behaviors".

See below for more information.

(none)
BLUR_RADIUSBlurring radius for the heat map1 - 325
COLORMAPColormap 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_COLORGradient start color for the heat mapHex color000000 (black)
GRADIENT_END_COLORGradient end color for the heat mapHex color000000 (black)
REVERSE_COLORMAPControls whether the COLORMAP should be reversed or not
  • TRUE reverses the colormap
  • FALSE keeps the colormap as is
FALSE

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.

Note

Contour mode only supports direct column references for X_ATTR, Y_ATTR, & VAL_ATTR parameters; column expressions are not supported.

Available parameters are:

NameDescriptionAllowable ValuesDefault Value
GRIDDING_METHODMethod to produce a regularly-spaced, rectangular array of values from potentially irregularly-spaced XY-val data. See below for more information.
  • INV_DST_POW -- Inverse Distance to a Power; a weighted average interpolator that can either be an exact or a smoothing interpolator
<Required>
VAL_ATTRAttribute to use to calculate the isolines.Column from the LAYERS source table list; must be of int, double, float, long, or decimal type<Required>
BG_COLORBackground colorHex notation in the format RRGGBB or AARRGGBB (to specify the alpha value)00000000 (transparent)
COLORIsoline color to be used when flooded contours are enabled; otherwise isolines will follow the colormapHex notation in the format RRGGBB or AARRGGBB, in which case the alpha value is used for the transparency of the flooded contours. The line itself is always opaque.FF000000
COLORMAPColormap for the contour or contour grid.
  • 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
ADJUST_LEVELSRecompute the minimum and maximum levels based on the current data in the viewport. Setting this will ignore the values of MIN_LEVEL and MAX_LEVEL.true or falsetrue
ADD_LABELSAdd label contour lines with the value of their level.true or falsefalse
ADJUST_GRIDAllows the grid size and search radius to be automatically varied based on the current data in the viewport.true or falsefalse
ADJUST_GRID_SIZESize of the sampling grid used to compute the fill and clustering ratios when ADJUST_GRID is set to 1.Number20
GRID_SIZENumber of subdivisions along the x axis when building the grid. The y axis will be set according to the aspect ratio.Number100
LABELS_FONT_FAMILYName of the font to use for labels. The font must be on the system.Any font codes available on all database serversSans
LABELS_FONT_SIZESize of the font to use for labels.Number between 4 and 4812
LABELS_INTERLEVEL_SEPARATIONWhen ADD_LABELS is set to true, more than one label can placed on the same isoline. This setting specifies the distance to use when separating labels of the same value (in percent of the total window size).Number between 0 and 5025
LABELS_INTRALEVEL_SEPARATIONWhen ADD_LABELS is set to true, labels are automatically separated to avoid overlap. This setting specifies the distance to use when separating labels of different values (in multiples of the font size).Number between 1 and 84
LABELS_MAX_ANGLEMaximum angle, in degrees, from the vertical to use when displaying labels.Number between 0 and 9060
LABELS_SEARCH_WINDOWWhen ADD_LABELS is set to true, a search window is used to rate the local quality of each isoline. Smooth, continuous, long stretches with relatively flat angles are favored. This setting is multiplied by the font size to set the final window size.Number between 1 and 84
LINE_SIZEThickness of the isolines to be shown. Set to 0 to disable isoline drawing.Number2
MAX_GRID_SIZEUpper limit (in cells) of the grid size when ADJUST_GRID is set to 1Number500
MAX_LEVEL

Maximum isoline value to be shown.

Note

If ADJUST_LEVELS is true (default) this value will be calculated automatically.

Number-1
MAX_SEARCH_CELLSMaximum number of cells to use once the SEARCH_RADIUS has been converted from percentage to cells. The higher the number, the higher the quality of the contour plot.Number100
MIN_GRID_SIZELower limit (in cells) of the grid size when ADJUST_GRID is set to 1Number10
MIN_LEVEL

Minimum isoline value to be shown.

Note

If ADJUST_LEVELS is true (default) this value will be calculated automatically.

Number-1
NUM_LEVELSNumber of equally-separated isolines to be shown.10 or greater10
RENDER_OUTPUT_GRIDShow the grid used to build the contour plot, which is equivalent to generating a flooded-contour. This affects the labels by clipping the area around them. The opacity of the flooded-contours is specified in COLOR.true or falsefalse
SEARCH_RADIUSNeighborhood of influence of sample data (in percent of the image/grid). See below for more information.Number10
SMOOTHING_FACTORAmount of smoothing of the contribution of neighboring points.Number between 0 and 10.000001
TEXT_COLORColor of labels textHex notation in the format RRGGBB or AARRGGBB (to specify the alpha value)FF000000

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

Note

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.

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:

NameDescriptionAllowable ValuesDefault Value
LABEL_LAYERName of table to renderValid table, in [schema_name.]table_name format, using standard name resolution rules<Required>
LABEL_X_ATTRName of column or expression containing label's position on the x-axisNumeric column or expression referencing the LABEL_LAYER source table list; must be of int, double, float, or long typeColumn x
LABEL_Y_ATTRName of column or expression containing label's position on the y-axisNumeric column or expression referencing the LABEL_LAYER source table list; must be of int, double, float, or long typeColumn y
LABEL_DRAW_BOXDraw a box around the label0 (false) or 1 (true)0
LABEL_DRAW_LEADERDraw a leader line from each label to its x,y point specified by LABEL_LEADER_X_ATTR & LABEL_LEADER_Y_ATTR columns0 (false) or 1 (true)0
LABEL_FILL_COLORColor of fill for boxHex color (with or without alpha values) or -1 (full transparency)FF000000
LABEL_FILTERBoolean expression used to filter which labels are included from LABEL_LAYER N/A
LABEL_FONTFont 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_LEADER_X_ATTRName of column or expression containing leader line's terminating position on the x-axis (the end opposite the label)Numeric column or expression referencing the LABEL_LAYER source table list; must be of int, double, float, or long typeN/A
LABEL_LEADER_Y_ATTRName of column or expression containing leader line's terminating position on the y-axis (the end opposite the label)Numeric column or expression referencing the LABEL_LAYER source table list; must be of int, double, float, or long typeN/A
LABEL_LINE_COLORColor of line for box & leader lineHex color (with or without alpha values) or -1 (full transparency)FF000000
LABEL_LINE_WIDTHWidth of line for box & leader lineNumber1
LABEL_TEXT_ANGLENumber of degrees clockwise to rotate the labelNumber0
LABEL_TEXT_COLORText colorHex color (with or without alpha values) or -1 (full transparency)FF000000
LABEL_TEXT_SCALEText scaling factorNumber1
LABEL_TEXT_STRINGText of label to renderAll printable characters(no text)
LABEL_X_OFFSETHorizontally offset the label rendering from the actual coordinate using the given valueNumberN/A
LABEL_Y_OFFSETVertically offset the label rendering from the actual coordinate using the given valueNumberN/A

Important

When using the labels mode, LABEL_LAYER is required.

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:

NameDescriptionAllowable ValuesDefault Value
ADD_LABELSAdd labels to isolines with the value of their level.true or falsefalse
BG_COLORBackground color of the generated image.Hex notation in the format RRGGBB or AARRGGBB (to specify the alpha value)00000000 (transparent)
COLORIsoline color to be used when flooded contours are enabled; otherwise, isolines will follow the colormap.Hex notation in the format RRGGBB or AARRGGBB, in which case the alpha value is used for the transparency of the flooded contours. The line itself is always opaque.FF000000
COLORMAPColormap for the isochrones
  • 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
COLOR_ISOLINESColor each isoline according to the colormap; otherwise, use the foreground color.true or falsetrue
CONCAVITY_LEVELFactor to qualify the concavity of the isochrone curves. The lower the value, the more convex (with 0 being completely convex and 1 being the most concave).Values (inclusive) between 0 and 10.5
DATA_MAX_XUpper bound for the x values. If not provided, it will be computed from the bounds of the input data.Number 
DATA_MAX_YUpper bound for the y values. If not provided, it will be computed from the bounds of the input data.Number 
DATA_MIN_XLower bound for the x values. If not provided, it will be computed from the bounds of the input data.Number 
DATA_MIN_YLower bound for the y values. If not provided, it will be computed from the bounds of the input data.Number 
GENERATE_IMAGEGenerates a PNG image of the isochrones in the response.true or falsetrue
GRAPH_NAMEName of the graph on which the isochrone is to be computed.A valid graph name 
GRID_SIZEWhen interpolating the graph solution to generate the isochrone, GRID_SIZE represents by the number of subdivisions along the x axis when building the grid (the y is computed using the aspect ratio of the output image).Positive integers100
HEIGHTHeight of the generated image (if applicable). If not provided, the aspect ratio multiplied by WIDTH is used.Number-1
IS_REPLICATEDReplicate the SOLVE_TABLE.true or falsetrue
LABELS_FONT_FAMILYWhen ADD_LABELS is set to true, name of the font to use for labels. The font must be on the system.Any font codes available on all database serversSans
LABELS_FONT_SIZEWhen ADD_LABELS is set to true, size of the font to use for labels.Number between 4 and 4812
LABELS_INTRALEVEL_SEPARATIONWhen ADD_LABELS is set to true, labels are automatically separated to avoid overlap. This setting specifies the distance to use when separating labels of different values (in multiples of the font size).Number between 1 and 84
LABELS_INTERLEVEL_SEPARATIONWhen ADD_LABELS is set to true, more than one label can placed on the same isoline. This setting specifies the distance to use when separating labels of the same value (in percent of the total window size).Number between 0 and 5025
LABELS_MAX_ANGLEWhen ADD_LABELS is set to true, maximum angle, in degrees, from the vertical to use when displaying labels.Number between 0 and 9060
LABELS_SEARCH_WINDOWWhen ADD_LABELS is set to true, a search window is used to rate the local quality of each isoline. Smooth, continuous, long stretches with relatively flat angles are favored. This setting is multiplied by the font size to set the final window size.Number between 1 and 84
LEVELS_TABLEName of the table to output the isochrones, containing levels and their corresponding WKT geometry. If no value is provided, the table is not generated.A valid table name, in [schema_name.]table_name format, using standard name resolution rules 
LINE_SIZEThe width of the contour lines in pixels.Number between 0 and 203
MAX_SOLUTION_RADIUSExtent of the search around SOURCE_NODE. Set to -1.0 for unrestricted search.Number-1.0
NUM_LEVELSNumber of equally-separated isochrones to compute.Positive integer1
PROJECTIONSpatial 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
 
REMOVE_PREVIOUS_RESTRICTIONSIgnore the restrictions applied to the graph during the creation stage and only use the restrictions specified in this request.true or falsefalse
RESTRICTIONSAdditional restrictions to apply to the nodes/edges of an existing graph. Restrictions must be specified using identifiers; identifiers are grouped as combinations. Identifiers can be used with existing column names, e.g., 'table.column AS RESTRICTIONS_EDGE_ID', expressions, e.g., 'column/2 AS RESTRICTIONS_VALUECOMPARED', or raw values, e.g., '{0, 0, 0, 1} AS RESTRICTIONS_ONOFFCOMPARED'. If using raw values in an identifier combination, the number of values specified must match across the combination. If REMOVE_PREVIOUS_RESTRICTIONS is set to true any provided restrictions will replace the existing restrictions. If REMOVE_PREVIOUS_RESTRICTIONS is set to false, any provided restrictions will be added (in the case of 'RESTRICTIONS_VALUECOMPARED') to or replaced (in the case of 'RESTRICTIONS_ONOFFCOMPARED')Valid restrictions 
RESTRICTION_THRESHOLD_VALUEValue-based restriction comparison. Any node or edge with a 'RESTRICTIONS_VALUECOMPARED' value greater than their RESTRICTION_THRESHOLD_VALUE will not be included in the solution.  
SEARCH_RADIUSWhen interpolating the graph solution to generate the isochrone, the SEARCH_RADIUS is the neighborhood of influence of sample data (in percent of the image/grid).Positive integer20
SOLVE_DIRECTIONSpecify the direction of the isochrones solution: either toward the SOURCE_NODE or leading away from it.from_source or to_source 
SOLVE_TABLEName of the table to host intermediate solve results containing the position and cost for each vertex in the underlying graph.A valid table name, in [schema_name.]table_name format, using standard name resolution rules""
SOURCE_NODEStarting vertex on the underlying graph from/to which the isochrones are created.  
TEXT_COLORWhen ADD_LABELS is set to true, color for the labels.Hex notation in the format RRGGBB or AARRGGBB (to specify the alpha values) or -1 (full transparency)FF000000
UNIFORM_WEIGHTSWhen specified, assigns the given value to all the edges in the graph. Note that weights provided in WEIGHTS_ON_EDGES will override this value.  
WEIGHTS_ON_EDGESAdditional weights to apply to the edges of an existing graph. Weights must be specified using identifiers; identifiers are grouped as combinations. Identifiers can be used with existing column names, e.g., 'table.column AS WEIGHTS_EDGE_ID', expressions, e.g., 'ST_LENGTH(wkt) AS WEIGHTS_VALUESPECIFIED', or raw values, e.g., '{4, 15, 2} AS WEIGHTS_VALUESPECIFIED'. Any provided weights will be added (in the case of 'WEIGHTS_VALUESPECIFIED') to or multiplied with (in the case of 'WEIGHTS_FACTORSPECIFIED') the existing weight(s). If using raw values in an identifier combination, the number of values specified must match across the combination.Valid weights 
WIDTHWidth of the generated image (if applicable).Positive integer512