SQL Functions

This topic covers all functions built into the Manifold query engine, called SQL functions or query functions, in a single long topic.  Some browers are slow to respond with very long topics, so this documentation also provides topics covering functions in smaller groups, as listed below.  

 

The Manifold query engine also supports declaring and calling functions, including script functions, functions in external files and compiled functions as .NET assemblies.  

 

 

 

Manifold has so many SQL functions they have been grouped into several topics:

 

 

 

 

 

 

 

 

The list of functions below uses the same nomenclature as the function templates in the Query Builder.  SQL functions take arguments as specified in angle < > brackets.  The data type or value type the function returns is given after the : colon.    For example, Chr(<value>) : <string> takes a numeric <value> and returns a text <string>, as noted in the description a string that is a single character.   CoordSystems() : <table> takes no arguments and returns a table.

 

Examples in the list below which use an ? expression evaluation command are intended to be run in a Command Window.   Do not add a semicolon ; character when using the ? command in a Command window.  When using the ? command we use CALL when the function returns more than just a value, for example, when it returns a table.

 

Indexes are always zero based: for example, in an object consisting of three branches the first branch is branch 0, the second is branch 1 and the third is branch 2.

 

This is a long list, so to find a function it is best when viewing this topic in a browser to do a Ctrl-F to open a Find box and to enter the function name of interest to be able to jump to that function.  The list in this topic is comprehensive but new items are often added with updates to Manifold and may appear in the product before they appear in this documentation.   See the list in the query builder tab of the Command Window for an authoritative list of operators, commands and functions.

Constants

See the SQL Constants and Literals topic for some useful constants.   For information on functions that use a <filter> argument or which produce a filter definition matrix, see the How Matrix Filters Work topic.

Aggregate Functions

For a discussion of aggregate functions, see the Aggregates topic.

 

Avg(<value>) : <value>

An aggregate function:  Returns the average value of the value field.

Corr(<value>, <value>) : <value>

An aggregate function:  Takes two parameters and computes correlation.  

Count(<value>) : <value>

An aggregate function:  Counts the number of non-NULL values in a field or expression or, as Count(*), the total number of records.  

Covar(<value>, <value>) : <value>

An aggregate function:  Takes two parameters and computes sample covariance.  

CovarPop(<value>, <value>) : <value>

An aggregate function:  Takes two parameters and computes population covariance.  

Diversity(<value>) : <value>

An aggregate function:  Returns the total number of different values in the value field. 

 

DiversityIndex(<value>) : <value>

An aggregate function:  Returns the diversity index of the value field, a measure of diversity:

 

1 - sum(individualcount^2) / (totalcount^2)

 

A diversity index of 0 means that all values are equal.

 

First(<value>) : <value>

An aggregate function:  Returns the first value for the specified field.  Does not skip NULLs.  Given that tables should be considered unordered, should be used with care, as the first item in an unordered list cannot be considered better than a random choice. Instead, use First with results tables that have been ordered with ORDER BY.

 

SELECT First([Product Name]) FROM [Products];

 

The query above reports a single, random product name.  

 

SELECT First([Product Name])

  FROM (SELECT [Product Name]

          FROM [Products]

          ORDER BY [Product Name]);

 

The above query reports the single product name that comes first in a list sorted by product name.

GeomMergeAreas(<geom>) : <geom>

An aggregate function:  Takes a set of areas and returns an area geom that contains branches.  Curves and Z values are removed.

GeomMergeLines(<geom>) : <geom>

An aggregate function:  Takes a set of lines and returns a line geom that contains branches.  Curves and Z values are removed.

GeomMergePoints(<geom>) : <geom>

An aggregate function:  Takes a set of points and returns a multipoint geom that contains branches.  Z values are removed.  

GeomUnionAreas(<geom>) : <geom>

An aggregate function: Given a set of geoms that contain areas returns a geom giving their union as a single area.  Discards lines and points.   Any touching or overlapping areas are unioned into a single branch of the area while areas that do not touch or overlap will be separate branches.

 

GeomUnionRects(<valuex4>) : <valuex4>

An aggregate function: Given a set of x4 values where each x4 value defines diagonally opposite corners of a rectangle, return a single x4 value that gives the union of those rectangles, that is the common bounding box of those rectangles.   

JoinAnd(<boolean>) : <boolean>

An aggregate function: Combine boolean values using the And operator and return a boolean value.

JoinBitAnd(<value>) : <value>

An aggregate function: Combine numeric values using the BitAnd operator and return a boolean value.

JoinBitOr(<value>) : <value>

An aggregate function: Combine numeric values using the BitOr operator and return a boolean value.

JoinBitXor(<value>) : <value>

An aggregate function: Combine numeric values using the BitXor operator and return a boolean value.

JoinOr(<boolean>) : <boolean>

An aggregate function: Combine boolean values using the Or operator and return a boolean value.

JoinXor(<boolean>) : <boolean>

An aggregate function: Combine boolean values using the Xor operator and return a boolean value.

Last(<value>) : <value>

An aggregate function: Returns the last value for the specified field.  Does not skip NULLs. Given that tables should be considered unordered, should be used with care, as the last item in an unordered list cannot be considered better than a random choice. Instead, use Last with results tables that have been ordered with ORDER BY.

 

SELECT Last([Product Name]) FROM [Products];

 

The query above reports a single, random product name.  

 

SELECT Last([Product Name])

  FROM (SELECT [Product Name]

          FROM [Products]

          ORDER BY [Product Name]);

 

The above query reports the single product name that comes last in a list sorted by product name.

Major(<value>) : <value>

An aggregate function:  Returns the the most frequently occurring value in the value field. If all values are different, Major reports the lowest.

 

Max(<value>) : <value>

An aggregate function:  Returns the maximum value for the specified field.  

 

SELECT Max([Population]) FROM [States Table];

 

Median(<value>) : <value>

An aggregate function:  Returns the median value for the specified field.  

 

SELECT Median([Population]) FROM [States Table];

 

Min(<value>) : <value>

An aggregate function:  Returns the minimum value for the specified field.  

 

SELECT Min([Population]) FROM [States Table];

 

StDev(<value>) : <value>

An aggregate function:  Returns the standard deviation of values found in this field in aggregated records, that is, the square root of the sample variance.

 

SELECT StDev([Population])

  FROM [Provinces Table];

 

StDevPop(<value>) : <value>

An aggregate function:  Returns the standard deviation of values found in this field in the entire table, that is, the square root of the population variance.   The method name is a mnemonic for the standard deviation for an entire population.

 

SELECT StDevPop([Population])

  FROM [Provinces Table];

 

StringJoinTokens(<value>, <separator>) : <value>

An aggregate function:  Given string values and a separator string, returns a single string where the values are separated by the separator

 

SELECT StringJoinTokens([First Name], ' -x- ')

  FROM [Employees];

 

Using the Nwind sample database, the above query results in a single record with a result field of:

 

Nancy -x- Andrew -x- Janet -x- Margaret -x- Steven -x- Michael -x- Robert -x- Laura -x- Anne -x- Albert -x- Tim -x- Caroline -x- Justin -x- Xavier -x- Laurent

 

The function can handle personalized separators for each passed value:

 

SELECT StringJoinTokens([First Name], CASE WHEN [First Name] LIKE 'A%' THEN ' -x- ' ELSE ' ==> ' END)

  FROM [Employees];

 

Results in:

 

Nancy -x- Andrew ==> Janet ==> Margaret ==> Steven ==> Michael ==> Robert ==> Laura -x- Anne -x- Albert ==> Tim ==> Caroline ==> Justin ==> Xavier ==> Laurent

 

Passing such personalized separators makes it possible to inject tokens that can be replaced by newline or other characters in output results.

 

Sum(<value>) : <value>

An aggregate function:  Given a value field returns the sum of the values in that field.  

 

SELECT Sum([Population]) FROM [Provinces Table];

 

See an example in the GROUP BY topic.

Var(<value>) : <value>

An aggregate function:  Given a value field returns sample variance.  

 

SELECT Var([Population]) FROM [States Table];

 

VarPop(<value>) : <value>

An aggregate function:  Given a value field returns population variance.  

 

SELECT VarPop([Population]) FROM [States Table];

 

Functions

Abs(<value>) : <value>

Returns the absolute value

Acos(<value>) : <radians>

Returns the arc cosine (inverse cosine) of the value.

Acosh(<value>) : <radians>

Returns the Inverse hyperbolic cosine

Asin(<value>) : <radians>

Returns the arc sine (inverse sine) of the value.

Asinh(<value>) : <radians>

Returns the inverse hyperbolic sine

Atan(<value>) : <radians>

Returns the arc tangent (inverse tangent) of the value.

Atan2(<y>, <x>) : <radians>

Returns the arc tangent (inverse tangent) of the ratio of y/x.

Atanh(<value>) : <radians>

Inverse hyperbolic tangent

BinaryStringBase64(<value>) : <string>

Takes a binary value and converts it to a base64-encoded string.

BinaryStringHex(<value>) : <string>

Takes a binary value and converts it to a hex-encoded string.  

BinaryWkbGeom(<wkb>) : <geom>

Takes WKB and returns a geom.  Supports EWKB as used by PostgreSQL.

Cbrt(<value>) : <value>

Cubic root

Ceil(<value>) : <value>

Return smallest integer greater than or equal to x.

CeilDecs(<value>, <decimals>) : <value>

Return smallest number to given number of decimal places that is greater than or equal to x.

Chr(<value>) : <string>

Takes an ASCII code number and returns the corresponding character.

Coalesce(<value>, ...) : <value>

Returns the first non-NULL value out of the list of values.

CollateCode(<collate>) : <collate-code>

The Collate function takes a <collate> string with collation definition options like thosed used by the COLLATE SQL command, and returns a numeric value that encodes that collation which can be used as the <collate-code> argument in functions that use collations.   If the collation definition is external, the function returns NULL.

 

? CollateCode('en-US, nocase, noaccent')

 

The above generates the number 934, which encodes the use of a US English collation insensitive to case and insensitive to accents.   Options for the <collate> string include:

 

  • <name> - A short string that specifies the collation language. Collations are identified by names such as en-US, en-GB and zh-CN.   Use neutral for the default collation language, or the name of a collation taken from a roster of over 150 supported collations, similar to those used by PostgreSQL.   Collations are identified by names such as en-US, en-GB and zh-CN.   An empty name is allowed and will specify the default collation.  The only option supported by neutral is nocase: all other options for neutral are ignored. The short form of '' for the entire default collation is accepted, but 'neutral, nocase' must spell the collation language as neutral and cannot omit it or use an empty string.
  • noaccent - Ignore diacritical marks, accents, and other similar characters, referred to as non-space characters in Unicode jargon.  The default is to use such characters when sorting.
  • nocase - Ignore case.  The default is case-sensitive sort order.
  • nokanatype - Ignore kana type for Asian languages.  The default is to utilize the kana type, so that two instances of the same character in, say, hiragana and katakana, are considered to be different when sorting.
  • nosymbols - Ignore symbols and punctuation.  The default is to utilize symbols and punctuation.
  • nowidth - Ignore character widths for Asian languages. The default is to utilize width, so that two instances of the same character which only vary in width are considered to be different when sorting.
  • wordsort - Ignore space between words, that is, sort only on the characters that make up words and not also the spaces between words. The default is that space between words matters when sorting, so that words are not treated distinctly but only the full content of the string, words and spaces both.

 

See the COLLATE topic.

CollateCodeDef(<collate-code>): <collate>)

Given a numeric code for a (non-external) collation, the CollateCodeDef function returns the collation definition string for that collation.    See the COLLATE topic.

Compare(<value>, <value>) : <value>

Return -1 if the first value is less than the second value, 1 if the first value is greater than the second and 0 if the first and second values are equal.  Can use any data type.

ComponentBounds(<component>, <forceCompute>): <valuex4>

Given a component report the bounds of the component as a rectangular extent given by a four part (x4) number given the diagonally opposite corners of the rectangle as x1,y1, x2 y2 values.

 

The <forceCompute> argument is a boolean flag controlling whether to compute bounds for a component that is not automatically maintaining bounds by reading the component records.

 

Examples of components that automatically maintain their bounds are images, and also drawings, and labels that are in a MAP file based on a table with an RTREE index on the needed geometry field.   Examples of components that do not automatically maintain their bounds are drawings and labels based on queries.

ComponentCoordSystem(<component>) : <system>

Takes a component and returns its coordinate system.  For maps and components that can participate in maps as layers (drawing, image, labels).

ComponentCoordSystemAutoXY(<component>): <system>

Takes a component and returns its coordinate system, and forces the coordinate system for an image to use XY axes. .  For maps and components that can participate in maps as layers (drawing, image, labels).

 

Because an image is stored in a special way, the axes of an image's coordinate system are always interpreted as XY / XYH. Using this function  allows passing the returned coordinate system without any further modifications to the coordinate converter object.

ComponentCoordSystemScaleXY(<component>): <valuex2>

Takes a component and returns a FLOAT64X2 value with local scales for X, Y and Z. If the component is in Latitude/Longitude, local scales for X and Y are approximated: images use scales at the center latitude of the image, and drawings use scales at zero latitude

ComponentCoordSystemScaleXYZ(<component>): <valuex3>

Takes a component and returns a FLOAT64X3 value with local scales for X, Y and Z. If the component is in Latitude/Longitude, local scales for X and Y are approximated: images use scales at the center latitude of the image, and drawings use scales at zero latitude

ComponentName(<component>) : <value>

Takes a component and returns its name.

ComponentPath(<component>, <child>) : <value>

Takes a pair of components and returns the path (across data sources) from one component to the other.

ComponentProperty(<component>, <property>) : <value>

Takes a component and a property name, and returns the value of the specified property.

ComponentType(<component>) : <value>

Takes a component and returns its type.

CoordConvert(<converter>, <geom>) : <geom>

Converts a geom from one coordinate system to another. The function takes a coordinate converter object and a geom value, and returns a new geom value.

CoordConverterIsIdentity(<converter>) : <value>

takes a coordinate converter object and returns true if it represents an identity operation (performs no conversion).   

CoordConverterIsScaleShift(<converter>) : <value>

CoordConverterIsScaleShift returns true if the conversion is limited to scale and shift.

CoordConverterIsScaleShiftSwap(<converter>) : <value>

CoordConverterIsScaleShiftSwap returns true if the conversion is limited to scale, shift and coordinate swap (XY to YX or vice versa).

CoordConverterIsXYZ(<converter>) : <value>

CoordConverterIsXYZ returns true if either target or source coordinate system is cartesian XYZ.

CoordConverterMake(<target>, <source>) : <converter>

Takes the definitions of target and source coordinate systems (in that order) and creates a coordinate converter object. Coordinate converter objects are treated syntactically like a table so we have to write

 

CALL CoordConverterMake(...)

 

Returns NULL if an coordinate converter object cannot be created.  That can happen due to an impossible combination of parameters in either of the coordinate systems.

CoordConverterMakePath(<target>, <source>, <hint>, <strict>): <converter>

Takes a pair of coordinate system and a conversion path hint, and returns a coordinate converter object that can be used to convert coordinates between the systems. The conversion path hint can be either 'EPSG:xxx' with the EPSG code of the transform to use in the path, or 'GRID:xxx' with the name of the grid file of the transform to use in the path. For a list of transforms that can be used to convert coordinates between the specified systems, use CoordTransformChoices.

 

Returns NULL if an coordinate converter object cannot be created.  That can happen due to an impossible combination of parameters in either of the coordinate systems, or due to an invalid coordinate conversion path, or due to a path that references a missing or invalid grid file.

CoordConverterSteps(<converter>) : <table>

Takes a coordinate converter object and reports conversion steps as a table.

CoordConvertPoint(<converter>, <valuex2>) : <valuex2>

Takes a coordinate converter object and an XY coordinate and returns the converted coordinate.

CoordConvertPoint3(<converter>, <valuex3>) : <valuex3>

Takes a coordinate converter object and an XYZ coordinate and returns the converted coordinate.

CoordConvertRect(<converter>, <valuex4>, <intermediate>) : <valuex4>

Takes a coordinate converter object, a rect value, and the optional number of intermediate divisions, and converts the rect to the desired coordinate system. If the number of intermediate divisions is positive, the function creates a grid of intermediate coordinates covering the rect, projects all these coordinates and uses the results to compute the shape of the resulting rect more accurately (useful when the projection is curvilinear).

CoordConvertTile(<converter>, <image>, <valuex4>, <interpolation>) : <tile>

Converts coordinate systems of tiles for images similar to how CoordConvert  converts coordinate systems for geoms.   The first argument is a converter from the coordinate system of the original image to the coordinate system of the new image. The second argument is the original image (passing the table with the image data will not work - we must pass the image). The third argument is the rectangle of the tile to produce in the coordinate system of the new image. If the rectangle is denormalized (xmin > xmax or ymin > ymax) or empty (xmin = xmax or ymin = ymax), the function returns NULL. If the rectangle coordinates are fractional, they are rounded to full pixels:  xmin and ymin are rounded down (Floor) and ymin and ymax are rounded up (Ceil).  The <interpolation> argument specifies interpolation type: 0 = nearest neighbor, 1 = bilinear, or 2 = bicubic.

CoordConvertTileSet(<converter>, <image>, <valuex4>, <divisions>, <interpolation>): <table>

Takes a coordinate converter object, an image in the source coordinate system, a rectangle in the target coordinate system, and an interpolation argument specifies interpolation type: 0 = nearest neighbor, 1 = bilinear, or 2 = bicubic.  Returns a table with image tiles projected to the target coordinate system using the standard projection method.  The result table returned by the function supports a BTREE index on XY fields, which allows efficiently using the function in a join directly without having to copy the returned data into a different table.

CoordConvertTileSetDirect(<converter>, <image>, <valuex4>, <divisions>): <table>

Takes a coordinate converter object, an image in the source coordinate system, a rectangle in the target coordinate system and a number of pixel subdivisions, and returns a table with image tiles projected to the target coordinate system, using the sub-pixel projection method.   The result table returned by the function supports a BTREE index on XY fields, which allows efficiently using the function in a join directly without having to copy the returned data into a different table.

CoordConvertTileSetDirectPar(<converter>, <image>, <valuex4>, <divisions>, <threads>): <table

A parallel form of the CoordConvertTileSetDirect function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the CoordConvertTileSetDirect function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.    The result table returned by the function supports a BTREE index on XY fields, which allows efficiently using the function in a join directly without having to copy the returned data into a different table.

CoordConvertTileSetPar(<converter>, <image>, <valuex4>, <divisions>, <threads>, <interpolation>): <table

A parallel form of the CoordConvertTileSet function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the CoordConvertTileSet function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.   The result table returned by the function supports a BTREE index on XY fields, which allows efficiently using the function in a join directly without having to copy the returned data into a different table.

CoordConvertTrace(<converter>, <valuex3>) : <table>

Takes a coordinate converter object and an XYZ coordinate and reports conversion steps as well as the intermediate conversion result after each step as a table.

CoordDatum(<manifold>) : <value>

Returns the definition of the datum with the specified Manifold ID.

CoordDatumDefault() : <value>

returns the definition of the default datum.

CoordDatumEpsg(<epsg>) : <value>

Returns the definition of the datum with the specified EPSG code.

CoordDatumParameters() : <table>

Returns a list of datum parameters.

 

? CALL CoordDatumParameters()

 

CoordDatums() : <table>

Returns a list of datums in the internal coordinate system database.

 

? CALL CoordDatums()

 

CoordMeasureArea(<measure>, <geom>): <value>

Takes a measure object and a geom for an area object and returns the area of the area object. The geom must be an area in the coordinate system of the measure object. The returned value is in the squared units of the measure object.

CoordMeasureBearing(<measure>, <geom>): <value>

Takes a measure object and a geom for a line object and returns the bearing of the line. The geom must be a line with a single branch in the coordinate system of the measure object, the bearing is computed from the first to last coordinate of the line. The returned value is in degrees.

CoordMeasureBearingPoint(<measure>, <valuex2>, <valuex2>): <value>

Takes a measure object and a pair of point (x2) values and returns the bearing from the first point to the second point. The point values must be in the coordinate system of the measure object. The returned value is in degrees.

CoordMeasureDistancePoint(<measure>, <valuex2>, <valuex2>): <value>

Takes a measure object and a pair of point (x2) values and returns the distance between the points. The point values must be in the coordinate system of the measure object. The returned value is in the units of the measure object.

CoordMeasureLength(<measure>, <geom>): <value>

Takes a measure object and a geom and returns length. The geom must be an area or a line in the coordinate system of the measure object. The returned value is in units of the measure object.

CoordMeasureMake(<system>, <unit>, <geodetic>): <value>

Takes a coordinate system definition, a unit name and a geodetic boolean flag and returns a measure object (similar to a coordinate converter object) that can be used to perform measurements.

  • If the coordinate system is Latitude / Longitude, and the unit is Latitude / Longitude degrees, measurements are Euclidean, performed in the specified Latitude / Longitude coordinate system.

  • If the coordinate system is Latitude / Longitude and the unit is metric, measurements are geodetic (computed on the surface of the ellipsoid) .

  • If the coordinate system is metric and the unit is Latitude / Longitude degrees, measurements are Euclidean, performed in the base Latitude / Longitude coordinate system of the specified coordinate system. The geometry values are converted to Latitude / Longitude as part of the process.

  • If the coordinate system is metric, the unit is metric, and the geodetic flag is FALSE, measurements are Euclidean, performed in the specified metric coordinate system.

  • If the coordinate system is metric, the unit is metric, and the geodetic flag is TRUE, measurements are geodetic (computed on the surface of the ellipsoid). The geometry values are converted to Latitude / Longitude as part of the process.

 

As with the CoordConverterMake function, the measure object returned by CoordMeasureMake is treated as a table and thus the function must be invoked with a CALL.   

 

For example, suppose our Mexico table has area geoms in the default Latitude / Longitude coordinate system.   We can get the first argument for CoordMeasureMake , the definition of that default Latitude / Longitude coordinate system, by using CoordSystemDefaultLatLon().

 

To get the geodetic area measurement we could write:

 

SELECT CoordMeasureArea(

  CALL CoordMeasureMake(CoordSystemDefaultLatLon(), 'Meter', TRUE),

     [Geom]

  )

  FROM [Mexico];

 

More efficiently, there is no need to recompute CoordMeasureMake for each record when it could be done once as part of the expression context:

 

VALUE @measure TABLE = CALL CoordMeasureMake(

  CoordSystemDefaultLatLon(), 'Meter', TRUE);

 

SELECT CoordMeasureArea(@measure, [Geom])

  FROM [Mexico];

 

CoordSystem(<manifold>) : <value>

Returns the definition of the coordinate system with the specified Manifold ID.  We can see a list of all coordinate systems with their EPSG IDs and Manifold IDs using CoordSystems().

 

? CoordSystem(612)

 

CoordSystemBase(<string>): <value>

Takes a coordinate system string and returns the base Latitude / Longitude coordinate system.

CoordSystemDefault() : <value>

Returns the definition of the default coordinate system.

 

? CoordSystemDefault()

 

CoordSystemDefaultLatLon() : <value>

Returns the definition of the default lat/lon coordinate system.

 

? CoordSystemDefaultLatLon()

 

 

CoordSystemEpsg(<epsg>) : <value>

Returns the definition of the coordinate system with the specified EPSG code.   

 

? CoordSystemEpsg(4326)

 

CoordSystemForceXY(<string>): <value>

Takes a coordinate system string and returns the same coordinate system with axes forced to XY order.  If the original coordinate system definition is an EPSG or SRID code, the new coordinate system is the same code with overrides.

CoordSystemMatchEpsg(<string>): <epsg>

Takes a coordinate system definition and returns the corresponding EPSG code. The EPSG code is taken from the name.  The definition of the referenced EPSG system is then checked against coordinate system parameters without local scales and offsets.

CoordSystemMatchEpsgBase(<string>): <epsg>

Takes a coordinate system definition and returns the EPSG code corresponding to its base lat/lon coordinate system. The EPSG code is taken from the name of the base.  The definition of the referenced EPSG system is then checked against datum parameters.

CoordSystemOverride(<string>, <json>) : <value>

Takes a coordinate system string and a JSON string with the parameter overrides, and composes a new coordinate system string merging the two together.

 

ALTER Table [WaterwaysTable] (

  ADD PROPERTY 'FieldCoordSystem.Geom'

     CoordSystemOverride('EPSG:4269', '{ "Axes":"XY" }')

);

 

CoordSystemParse(<string>) : <value>

Takes a string (JSON / XML / any of the subformats with prefixes like "EPSG:xxx") and parses it into a coordinate system.  Parsing coordinate system data supports OSGEO:xxx codes (used in TMS), as well as ESRI and OPENLAYERS codes for web Mercator.

CoordSystemParseEpsg(<string>) : <epsg>

Takes a coordinate system string, checks if it specifies an EPSG code, and if so, returns the code.

CoordSystemParseOverrides(<string>) : <json>

Takes a coordinate system string and returns parameter overrides if they exist.

CoordSystemParseSrid(<string>) : <srid>

Takes a coordinate system string, checks if it specifies an SRID code (a coordinate system local to a database), and if so, returns the code.

CoordSystemParseSridSubtype(<string>) : <subtype>

Takes a coordinate system string, checks if it specifies an SRID code, and if so, returns the SRID subtype.  For example, 'SRID:SDE:2230' returns 'SDE'.  The table with the definition of the coordinate system is named 'MFD_SRID_SDE'.

CoordSystemPlain(<string>): <value>

Takes a coordinate system string and returns the same coordinate system with local offsets set to 0 and local scales set to 1.

CoordSystemTypeParameters(<system>, <withScalesShifts>) : <table>

Returns a list of parameters for the specified coordinate system type.  Example:

 

? CALL CoordSystemTypeParameters('Lambert Conformal Conic', TRUE)

 

CoordSystemScaleXY(<string>): <valuex2>

Takes a coordinate system definition and returns a FLOAT64X2 value for local scales for X and Y.

CoordSystemTypes() : <table>

Returns a list of supported coordinate system types.  

 

? CALL CoordSystemTypes()

 

CoordSystemXml(<system>) : <xml>

Takes a coordinate system definition and converts it to Manifold 8 XML. Not all systems can be converted (example: EPSG:5515 can not be converted, because the system type is modified Krovak and Manifold 8 does not support that), but the vast majority can.

 

? CoordSystemXml('EPSG:4200')

 

? CoordSystemXml('{ "System": "Azimuthal Equidistant" }')

 

CoordSystemWkt(<string>, <strict>): <wkt>

Takes a coordinate system definition and a <strict> boolean flag and returns the WKT (PRJ) representation. If the coordinate system cannot be represented as WKT, the function returns a NULL value. If the <strict> flag is false, the function maps coordinate systems that cannot be represented as WKT to close variants.  For example, the Lambert conformal conic variant for Michigan is mapped to Lambert conformal conic.

 

? CoordSystemWKT('EPSG:4326', TRUE)

 

Returns the WKT string:

 

GEOGCS["GCS_WGS_84", DATUM["D_WGS_84", SPHEROID["WGS_1984", 6378137, 298.25722356300156]], PRIMEM["Greenwich", 0.0], UNIT["Degree", 0.017453292519943295], AXIS["Lat", NORTH], AXIS["Lon", EAST]]

CoordSystemWkt2(<string>, <strict>): <wkt2>

Takes a coordinate system definition and a <strict> boolean flag and returns the WKT2 (updated version of WKT) representation. If the coordinate system cannot be represented as WKT2, the function returns a NULL value. If the <strict> flag is false, the function maps coordinate systems that cannot be represented as WKT2 to close variants.  For example, the Lambert conformal conic variant for Michigan is mapped to Lambert conformal conic.

 

? CoordSystemWKT2('EPSG:4326', TRUE)

 

Returns the WKT2 string:

 

GEODCRS["WGS 84", DATUM["WGS 84", ELLIPSOID["WGS 1984", 6378137, 298.257223563, LENGTHUNIT["metre", 1.0]]], CS[ellipsoidal, 2], AXIS["latitude", north, ORDER[1]], AXIS["longitude", east, ORDER[2]], ANGLEUNIT["Degree", 0.017453292519943295], ID["EPSG", 4326]]

 

See the ESRI presentation PDF on WKT2.

CoordSystems() : <table>

Returns a list of coordinate systems in the internal database.  

 

? CALL CoordSystems()

CoordTransform(<manifold>) : <value>

Returns the definition of the coordinate transform identified by the specified Manifold ID.  Use CoordTransforms() to see a list of IDs for transforms.  

 

? CoordTransform(399)

 

Manifold ID 399 is the same transform as EPSG:1064.

 

CoordTransformChoices(<target>, <source>): <table>

Takes a pair of coordinate systems and returns a table of transforms that can be used to convert coordinates between them.

CoordTransformEpsg(<epsg>) : <value>

Returns the definition of the coordinate transform identified by the specified EPSG code.  Use CoordTransforms() to see a list of EPSG codes for transforms.

 

? CoordTransformEpsg(1064)

 

EPSG:1064 is the same transform as Manifold ID 399.

 

CoordTransforms() : <table>

Returns a list of coordinate system transforms in the internal database.

 

? CALL CoordTransforms()

 

See the SQL Example: List Transformation Grids topic.

CoordTransformTypeParameters(<transform>) : <table>

Returns a list of parameters for the specified coordinate system transform type. The returned table contains a field for the parameter name and a field for the default value.

 

? CALL CoordTransformTypeParameters('Complex Polynomial (3)')

 

CoordTransformTypes() : <table>

Returns a list of supported coordinate transform types.

 

? CALL CoordTransformTypes()

 

CoordUnit(<manifold>) : <value>

Returns the definition of the coordinate system unit for the coordinate system unit  identified by the specified Manifold ID.  Use CoordUnits() to see a list of Manifold IDs for units.

 

? CoordUnit(17)

 

The coordinate system unit specified by Manifold ID 17 is the same, Clarke's Foot, as specified by EPSG:9005.

 

CoordUnitByName(<name>) : <value>

Takes a coordinate system unit name and returns the unit definition.  Remember to escape any single quote ' characters used in the name of a unit.

 

? CoordUnitByName('Clarke\'s Foot')

 

CoordUnitDefault() : <value>

Returns the definition of the default / default coordinate system unit.

 

? CoordUnitDefault()

 

CoordUnitDefaultLatLon() : <value>

Returns the definition of the lat/lon coordinate system unit.

 

? CoordUnitDefaultLatLon()

 

CoordUnitEpsg(<epsg>) : <value>

Returns the definition of the coordinate system unit for the coordinate system unit identified by the specified EPSG code.   Use CoordUnits() to see a list of EPSG codes for units.

 

 ? CoordUnitEpsg(9005)

 

The coordinate system unit specified by EPSG:9005 is the same, Clarke's Foot, as specified by Manifold ID 17.

 

CoordUnits() : <table>

Returns a list of coordinate system units. Returned tables contain a field for the Manifold ID, a field for the corresponding EPSG code, which can be NULL, a JSON definition of the described object, and sometimes additional data.

 

? CALL CoordUnits()

 

Cos(<radians>) : <value>

Returns the cosine of the value.

Cosh(<radians>) : <value>

Returns the hyperbolic cosine of the value.

DataLength(<value>) : <value>

Takes a value of an arbitrary type and returns its length in bytes. String values include the closing zero (and can be either ANSI or Unicode).  The DataLength of a NULL value is also NULL.

 

? DataLength('Manifold')

 

Text literals entered into the Command window are stored as Unicode internally using UTF16, that is, two bytes per character, so the above example gives a result of float64: 18, meaning 18 bytes are used for the string: two bytes for each of the 8 characters in the word "Manifold" plus two more bytes for the closing zero.   

 

If we wanted to compute the length of the string as ANSI text using one byte per character we could cast the default Unicode of string literals into the ANSI data type of VARCHAR by writing

 

? DataLength(CAST ('Manifold' AS VARCHAR))

 

for a result of float64: 9, meaning one byte for each of the 8 characters plus one byte for the closing zero.

DateTimeDay(<date>) : <value>

Given a datetime value returns the day of the month.  The example returns 21.

 

? DateTimeDay(#01/21/2017#)

 

DateTimeHour(<date>) : <value>

Given a datetime value returns the hour of the day, reporting the hour using 24 hour time.  

 

? DateTimeHour(#01/21/2017 12:05:15#)

? DateTimeHour(#01/21/2017 08:05:15 PM#)

? DateTimeHour(#01/21/2017 08:05:15 AM#)

? DateTimeHour(#01/21/2017 20:05:15#)

 

DateTimeMillisecond(<date>) : <value>

Given a datetime value returns the millisecond value for the time.

 

? DateTimeMillisecond(#01/21/2017 12:01:15.126#)

 

DateTimeMinute(<date>) : <value>

Given a datetime value returns the minute of the hour value for the time. The example returns 5.

 

? DateTimeMinute(#01/21/2017 12:05:15#)

 

DateTimeMonth(<date>) : <value>

Given a datetime value returns the month of the year.  The example returns 1 for January.

 

? DateTimeMonth(#01/21/2017 12:05:15#)

 

DateTimeSecond(<date>) : <value>

Given a datetime value returns the second of the minute.   The example returns 15.

 

? DateTimeSecond(#01/21/2017 12:05:15#)

 

DateTimeYear(<date>) : <value>

Given a datetime value returns the year.   The example returns 2017.

 

? DateTimeYear(#01/21/2017 12:05:15#)

 

Erf(<value>) : <value>

Computes error function.

Erfc(<value>) : <value>

Computes complementary error function.

Exp(<value>) : <value>

Computes the exponential function: Return e to the power of the value.  For a value of x, returns e^x.

Exp10(<value>) : <value>

Base 10 exponent: Return 10 to the power of the value. For a value of x, returns 10^x.

Exp2(<value>) : <value>

Base 2 exponent: Return 2 to the power of the value. For a value of x, returns 2^x.

Expm1(<value>) : <value>

For a value of x, returns e^x-1.

Floor(<value>) : <value>

Returns the largest integer that is less than or equal to the value.     See the note below on the difference between Floor and Trunc functions.

FloorDecs(<value>, <decimals>) : <value>

Returns the largest number to the given number of decimal places that is less than or equal to the value.     See the note below on the difference between Floor and Trunc functions.

Fract(<value>) : <value>

Returns the decimal fractional portion of the value.

FractDecs(<value>, <decimals>) : <value>

Returns the decimal fractional portion of the value beyond the specified number of decimal places.

GeocodeAddress(<dataSource>, <address>) : <valuex2>

Given a geocoding data source and an address, returns the longitude/latitude coordinates as a float64x2 value.   See the Street Address Geocoding topic.

 

Example: using a Google geocoding data source, returns the longitude,latitude coordinates for the specified street address in New York state.

 

? GeocodeAddress([Google], '16 Bush Lane Ithaca NY')  

  

Example: using a Google geocoding data source, returns the longitude,latitude coordinates for 'Chicago'.

 

? GeocodeAddress([Google], 'Chicago')

 

GeocodeAddressMatches(<dataSource>, <address>) : <table>

Given a geocoding data source and an address, returns a table of matches. Each match is a string with the format of the string depending on the geocoding server in use.   Most geocoding servers return JSON.  See the Street Address Geocoding topic.

 

? CALL GeocodeAddressMatches([Google], 'Bush Lane, Ithaca NY')

 

(In the Command Window when trying the above, hover the mouse over a Results table cell to see the JSON for that cell in a tooltip.)

GeocodeAddressSupported(<dataSource>) : <value>

Given a geocoding data source, returns true if the data source supports GeocodeAddress and GeocodeAddressMatches functions.  See the Street Address Geocoding topic.

 

? GeocodeAddressSupported([Google])

 

GeocodeLocationMatches(<dataSource>, <valuex2>) : <table>

Reverse geocoding.  Given a geocoding data source and a longitude/latitude location as a float64x2 value, returns a table of matches around that location.  See the Street Address Geocoding topic.

 

? CALL GeocodeLocationMatches([Google], VectorMakeX2(-76.4866069,42.495071) )

 

(In the Command Window when trying the above, hover the mouse over a Results table cell to see the JSON for that cell in a tooltip.)

 

GeocodeLocationSupported(<dataSource>) : <value>

Given a geocoding data source, returns true if the data source supports the GeocodeLocationMatches function.   See the Street Address Geocoding topic.

 

? GeocodeLocationSupported([Google])

 

GeomAdjacent(<geom>, <geom>, <tolerance>) : <value>

Given two geoms returns true if they are adjacent. A tolerance of zero means automatic tolerance.   For the definition of adjacent see the Join topic.

GeomArea(<geom>, <tolerance>) : <value>

Given a geom that contains an area object, returns the area (Euclidean planar computation) of that area object in square units of measure used by the coordinate system.  A tolerance of zero means automatic tolerance.

 

SELECT GeomArea([Geom], 0) AS [Computed Area] FROM [Mexico];

 

GeomAreaGeo(<geom>, <major>, <eccentricity>, <tolerance>): <value>

Given a geom that contains an area object, and values for major axis, eccentricity, and tolerance, returns the geodetic area (computed on the surface of the ellipsoid) of that area object.  A tolerance of zero means automatic tolerance.

 

The geom value must be an area in Latitude / Longitude, with X (longitude) and Y (latitude) expressed in degrees. The returned value is in squared units of the major axis (typically, meters, for a returned value in square meters).

 

Looking at the Custom tab of the Base Coordinate System dialog for the WGS84 base used for Latitude / Longitude projection, we can see the major axis is 6378137.01 and the eccentricity is 0.08181919084262149

 

Given a Mexico drawing of provinces as areas in Latitude / Longitude coordinate system, we can write:

 

SELECT GeomAreaGeo([Geom], 6378137.01, 0.08181919084262149, 0) AS [Geodetic Area] FROM [Mexico];

GeomBearing(<geom>): <value>

Given a geom that contains a line object, returns the bearing (Euclidean planar computation) of that line object. The line must have a single branch.

 

The bearing is computed from the first to last coordinate of the line. The returned value is in degrees.

GeomBearingGeo(<geom>, <major>, <eccentricity>): <value>

Given a geom that contains a line object, and values for major axis, and eccentricity, returns the geodetic bearing (computed on the surface of the ellipsoid) of that line object.  

 

The geom value must be a single-branch line in Latitude / Longitude, with X (longitude) and Y (latitude) expressed in degrees.

 

The geodetic bearing is computed from the first to last coordinate of the line, using Vincenty's formulae.  The returned value is in degrees.

GeomBearingPoint(<valuex2>, <valuex2>): <value>

Given a pair of point (x2) values, returns the bearing (Euclidean planar computation) from the first point to the second point.  The returned value is in degrees.

GeomBearingPointGeo(<valuex2>, <valuex2>, <major>, <eccentricity>): <value>

Given a pair of point (x2) values,  and values for major axis, and eccentricity,  returns the geodetic bearing (computed on the surface of the ellipsoid) from the first point to the second point, computed using Vincenty's formulae. 

 

The point values must be in Latitude / Longitude, with X (longitude) and Y (latitude) expressed in degrees.  The returned value is in degrees.

GeomBoundedAreas(<geom>, <tolerance>): <table>

Given line objects, creates areas in regions entirely enclosed by overlapping or otherwise touching lines.  Areas and points are ignored.  The Tolerance value specifies how close lines must be to each other to be considered "touching."

 

Line objects are normally merged before being used as the geom in this function, for example, as in:

 

GeomBoundedAreas(GeomMergeLines([Geom]), 0))

 

GeomBounds(<geom>) : <geom>

Given a geom, return a geom that in the case of areas is the border of the area and in the case of lines is the two end coordinates of the line as a multipoint.  NULL is returned for points.  

GeomBoundsCircle(<geom>, <tolerance>) : <geom>

Given a geom, return a geom for an area object that in the case of areas or lines is the minimal enclosing circle.  NULL is returned for points. A tolerance of zero means automatic tolerance.  

GeomBoundsRect(<geom>) : <valuex4>

Given a geom, return a float64x4 value that gives the location of diagonally opposite corners which define a vertically oriented rectangle that is the minimum enclosing rectangle for areas or lines.  NULL is returned for points. 

 

Use the GeomMakeRect function to create a rectangular area object from the float64x4 value returned by GeomBoundsRect, as in

 

UPDATE (

  SELECT [mfd_id],  [Geom],

    GeomMakeRect(GeomBoundsRect([Geom])) AS [n_Geom]

  FROM [Table Drawing]

) SET [Geom] = [n_Geom];

 

GeomBoundsRectRotated(<geom>, <tolerance>) : <geom>

Given a geom, return a float64x4 value that gives the location of diagonally opposite corners which define a rectangle of any orientation that is the minimum enclosing rectangle for areas or lines.  NULL is returned for points.  A tolerance of zero means automatic tolerance.

GeomBranch(<geom>, <branch>) : <geom>

Takes a geom and a branch number (0 is the first branch) and returns the specified branch as a geom.

GeomBranchCount(<geom>) : <value>

Takes a geom and returns the number of branches in that geom.

GeomBranchFirst(<geom>, <branch>) : <value>

Given a geom and a branch number (0 is the first branch) returns the index of the first coordinate in the specified branch.

GeomBranchLast(<geom>, <branch>) : <value>

Given a geom and a branch number (0 is the first branch) returns the index of the last coordinate in the specified branch.

GeomBuffer(<geom>, <distance>, <tolerance>) : <geom>

Given a geom, a distance and a tolerance, returns a geom for an area object the border of which is the specified distance from any part of the object in the geom.   A tolerance of zero means automatic tolerance.

GeomCenter(<geom>, <tolerance>) : <valuex2>

Given a geom returns a float64x2 value that specifies the location of the center of the minimum enclosing circle for areas and lines and which for points specifies the location of the point.   A tolerance of zero means automatic tolerance.

GeomCenterInner(<geom>, <tolerance>) : <valuex2>

Given a geom returns a float64x2 value that specifies the location of the center of the minimum enclosing circle for areas, with the location adjusted so that it falls within the area object.   NULL is returned for lines and points.  A tolerance of zero means automatic tolerance.

GeomCenterWeight(<geom>, <tolerance>) : <valuex2>

Given a geom returns a float64x2 value that specifies the location of the balance point  for areas   NULL is returned for lines and points.  A tolerance of zero means automatic tolerance.

GeomClip(<geom>, <geom>, <inner>, <tolerance>) : <geom>

Given two geoms, use the geom in the second argument to "cookie cut," that is, to clip, the geom in the first argument, returning the result as a geom.   If the <inner> argument is true, leave the inner portion of the cut.   If the <inner> argument is false, leave the outer portion.   A tolerance of zero means automatic tolerance.   See illustrations and discussion in the Example: Clip Areas with a Transform Expression topic.

GeomContains(<geom>, <geom>, <tolerance>) : <value>

Given two geoms returns true if the first geom contains the second geom. A tolerance of zero means automatic tolerance.   For the definition of contains see the Join topic.

 

Example: A table contains a geom field called Buffer which are buffer areas that are larger than and were created from objects in the Geom field using the GeomBuffer function.  The Buffer objects contain the Geom objects.  

 

SELECT GeomContains([Buffer], [Geom], 0) FROM [Table];

 

The above returns a results table where all rows have 1 for true because all of the Buffer objects fully contain the corresponding Geom object.

 

SELECT GeomContains([Geom], [Buffer], 0) FROM [Table];

 

The above returns a results table where all rows have 0 for false, because none of the Geom objects contain the corresponding Buffer object.  

GeomConvertToArea(<geom>) : <geom>

Takes a geom of arbitrary type and converts it to an area geom. Branches are auto-closed (if the starting coordinate of the branch does not coincide with the ending coordinate, the starting coordinate is added once again at the end). Curves and Z values are preserved. Points are converted into pathological areas defined by three coordinates that are all at the same location.

GeomConvertToLine(<geom>) : <geom>

Takes a geom of arbitrary type and converts it to a line geom. Curves and Z values are preserved. Points are converted into pathological lines defined by two coordinates that are both at the same location.

GeomConvertToPoint(<geom>, <keepBranches>) : <geom>

Takes a geom of arbitrary type and converts it to a point geom. Converting objects such as areas, lines or multipoints will result in a multipoint.  The <keepBranches> argument is true or false, controlling whether to keep original branches (true) or join all coordinates into a single branch (false). Z values are preserved.

GeomConvexHull(<geom>, <allowSegmentPoint>,  <tolerance>) : <geom>

Given a geom, return an area object geom that is the convex hull enclosing the geom.  The allowSegmentPoint> boolean parameter specifies what is returned when the produced convex hull is a single point or a straight line segment.  When false, NULL is returned.  When true, an area with coincident coordinates is returned.  A tolerance of zero means automatic tolerance.   

GeomCoordCount(<geom>) : <value>

Given a geom returns the number of coordinates in the object the geom contains.  A triangular area contains 4 coordinates because the last coordinate is the same as the first to close the area.

GeomCoordLine(<geom>, <position>) : <valuex2>

Given a geom and a distance position, returns the coordinate on the line at the specified distance from the start of the line.  The function considers all line branches: If the first branch ends before the specified distance, the function moves on to check the second branch and so on, until the distance is reached. If the distance is negative or greater than the total length of all line branches, the function returns a NULL value.

 

 

GeomCoordXY(<geom>, <coord>) : <valuex2>

Given a geom and the index of a coordinate in that geom (0 based numbering, the first coordinate is the 0 coordinate), returns the value of that coordinate as a float64x2 value, representing the x and the y coordinate numbers.

GeomCoordXYZ(<geom>, <coord>) : <valuex3>

Given a geom and the index of a coordinate in that geom (0 based numbering, the first coordinate is the 0 coordinate), returns the value of that coordinate as a float64x3 value, representing the x, y and z coordinate numbers.

 

To test if a geom has a Z value, use GeomHasZ. To set the Z values for all coordinates of a geom to a specified value, use GeomSetZ.   To remove all Z values, use GeomRemoveZ. To read the Z value of the first coordinate of a geom, use

 

 VectorValue(GeomCoordXYZ([Geom],0),2)

GeomDistance(<geom>, <geom>, <tolerance>) : <value>

Takes two geoms and returns the Euclidean distance between the geoms, reported in whatever units are used for the geoms. The geoms are assumed to be in the same coordinate system.   A tolerance of zero means automatic tolerance.

GeomDistancePoint(<valuex2>, <valuex2>) : <value>

Takes a pair of point (x2) values and returns the Euclidean distance in the 2D plane between the locations defined by these values.

GeomDistancePoint3(<valuex3>, <valuex3>) : <value>

Takes a pair of point (x3) values and returns the Euclidean distance in 3D space between the locations defined by these values.

GeomDistancePointGeo(<valuex2>, <valuex2>, <major>, <eccentricity>): <value>

Takes a pair of point (x2) values, and values for major axis, and eccentricity, and returns the geodetic distance (computed on the surface of the ellipsoid) from the first point to the second point, computed using Vincenty's formulae. 

 

The point values must be in Latitude / Longitude, with X (longitude) and Y (latitude) expressed in degrees.  The returned value is in units of the major axis

GeomFlip(<geom>, <horz>, <vert>): <geom>

Takes a geom,  a boolean to specify horizontal flipping, and a boolean to specify vertical flipping, and returns a geom flipped horizontally and vertically as specified, about the centroid of the object.   Z values are preserved and 2D curvilinear segments are preserved, but 3D curvilinear segments  are replaced with 3D straight line segments.

GeomGml(<geom>, <system>) : <gml>

Takes a geom and an optional coordinate system (pass an empty string for no optional coordinate system) and returns GML for the geom.

 

SELECT GeomGml([Geom],'') FROM [Table];

 

for no optional coordinate system, and

 

SELECT GeomGml([Geom],'EPSG:4200') FROM [Table];

 

to specify EPSG:4200 as the coordinate system.

GeomHasCurves(<geom>) : <value>

Takes a geom and returns true if the geom has any curvilinear segments.  

GeomHasZ(<geom>) : <value>

Takes a geom and returns true if the geom has a Z value, that is, is 3D.

 

To set the Z values for all coordinates of a geom to a specified value, use GeomSetZ.   To remove all Z values, use GeomRemoveZ. To read the Z value of the first coordinate of a geom, use

 

 VectorValue(GeomCoordXYZ([Geom],0),2)

GeomInflateRect(<valuex4>, <inflatex2>): <valuex4>

 

GeomInflateRectTileSize(<valuex4>, <tilesizex2>): <valuex4>

A rect is a rectangular extent given by a four part (x4) number given the diagonally opposite corners of the rectangle as x1,y1, x2,2 values.  To inflate a rect means to increase the size of the rectangle, and to deflate a rect means to decrease the size of the rectangle.

 

See the discussion of rects in the SQL Example: Miscellaneous SQL Functions topic.

 

GeomInflateRect inflates a rect by increasing the size of the rectangle by the given X,Y values in the two part (x2) <inflatex2> value.   If the X or Y values are negative, the rectangle will be deflated, that is reduced by those values.

 

Consider a rectangle defined by a lower left x1,y1 corner of 0,0 and an upper right x2, y2 corner of 10,10.   We want to inflate the rectangle by two units in both X and Y.

 

In the Command Window we run the expression:

 

? GeomInflateRect(VectorMakeX4(0,0,10,10), VectorMakeX2(2,2))

 

That yields the result:

 

float64x4: [ -2, -2, 12, 12 ]

 

The result gives a new rect, with a new lower left corner of -2,-2 and a new upper right corner of 12,12.    The overall size of the rectangle has been increased by 2 units in both X and Y direction.  

 

Suppose we run the expression:

 

? GeomInflateRect(VectorMakeX4(0,0,10,10), VectorMakeX2(-2,-2))

 

That yields the result:

 

float64x4: [ 2, 2, 8, 8 ]

 

The new rect has been contracted by two units in X and Y dimension, with a new lower left corner of 2,2 and a new upper right corner of 8,8.

 

GeomInflateRectTileSize takes a <tilesizex2> argument giving the size of a tile, such as 128,128, and adjusts the rect size by inflating it to cover whole tiles of the given size.

 

Consider a rectangle defined by a lower left x1,y1 corner of 0,0 and an upper right x2, y2 corner of 1040,1040.   We want to inflate the rectangle so the extent exactly covers a whole number of 128,128 tiles in both X and Y dimension

 

In the Command Window we run the expression:

 

? GeomInflateRectTileSize(VectorMakeX4(0,0,1040,1040),

    VectorMakeX2(128,128))

 

That yields the result:

 

float64x4: [ 0, 0, 1152, 1152 ]

 

The result gives a new rect, with a new lower left corner of 0,0 and a new upper right corner of 1152,1152.    Note that 1152 is exactly 9 tiles of width or height 128.

 

The GeomInflateRectTileSize function always inflates, increasing the size of the rect to the next whole number of tiles.

GeomIntersectLines(<geom>, <geom>, <tolerance>) : <geom>

Takes a set of lines and returns their intersection points as a geom.  The geom will be one point, one intersection and will be a multipoint if there are multiple intersections.    A tolerance of zero means automatic tolerance.

GeomIntersects(<geom>, <geom>, <tolerance>) : <value>

Given two geoms returns true if they intersect. A tolerance of zero means automatic tolerance.   For the definition of intersect see the Join topic.

GeomIsArea(<geom>) : <value>

Returns true if the geom is an area.

GeomIsLine(<geom>) : <value>

Returns true if the geom is a line.

GeomIsLineClosed(<geom>): <value>

Returns true if each branch in a line geom is closed, that is, if each branch has the starting coordinate equal to the ending coordinate.

GeomIsNormalized(<geom>) : <value>

Returns true if the geom is normalized.  

 

The system keeps track of geoms that have been normalized.  Normalized geometry values store an explicit normalized flag plus additional normalize data which allows quickly transforming geometry to normalized form required by OGC and the different normalized form required by ESRI.

GeomIsPoint(<geom>) : <value>

Returns true if the geom is a point.

GeomJsonGeo(<geom>, <system>) : <json>

Takes a geom and an optional coordinate system (pass an empty string for no optional coordinate system) and returns GeoJSON for the geom.

 

SELECT GeomJsonGeo([Geom],'') FROM [Table];

 

for no optional coordinate system, and

 

SELECT GeomJsonGeo([Geom],'EPSG:4200') FROM [Table];

 

to specify EPSG:4200 as the coordinate system.

GeomLength(<geom>, <tolerance>) : <value>

Given a geom returns the length of lines and areas.  NULL is returned for points. A tolerance of zero means automatic tolerance.  The length of an area object is the length of its boundary, that is, the perimeter of the area.  The length reported for a branched object is the sum of the lengths of the branches.

 

SELECT GeomLength([Geom], 0) FROM [Table];

 

GeomLengthGeo(<geom>, <major>, <eccentricity>, <tolerance>): <value>

Given a geom that contains an area or a line object, and values for major axis, eccentricity, and tolerance, returns the geodetic length (computed on the surface of the ellipsoid) of that object, computed using Vincenty's formulae  A tolerance of zero means automatic tolerance.

 

The length of an area object is the length of its boundary, that is, the perimeter of the area.  The length reported for a branched object is the sum of the lengths of the branches.

 

The geom value must be an area or line in Latitude / Longitude, with X (longitude) and Y (latitude) expressed in degrees. The returned value is in units of the major axis.

 

Looking at the Custom tab of the Base Coordinate System dialog for the WGS84 base used for Latitude / Longitude projection, we can see the major axis is 6378137.01 and the eccentricity is 0.08181919084262149

 

Given a Mexico drawing of provinces as areas in Latitude / Longitude coordinate system, we can write:

 

SELECT GeomLengthGeo([Geom], 6378137.01, 0.08181919084262149, 0) AS [Geodetic Length] FROM [Mexico];

GeomLinearize(<geom>, <tolerance>, <limit>) : <geom>

Convert curvilinear segments to straight line segments. Takes a geom, linearizes all curvilinear segments and returns the result.   A tolerance of zero means automatic tolerance. The linearization process is guided by the tolerance value and the maximum number of coordinates, 1 or more specified as the <limit> argument, to which a single curve part (for example, between two control points of a spline) of a curvilinear segment will be expanded.

GeomMakeCircle(<valuex2>, <radius>) : <geom>

Takes an x2 value that defines the center and a radius value and returns a geom for a circular area object centered on that location with that radius.  

GeomMakePoint(<valuex2>) : <geom>

Takes an x2 value that defines a location and returns a geom for a point object at that location.

GeomMakePoint3(<valuex3>) : <geom>

Takes an x3 value that defines a 3D location (X, Y and Z) and returns a geom for a 3D point object at that location.

GeomMakeRect(<valuex4>) : <geom>

Takes an x4 value that defines diagonally opposite corners of a rectangle and returns a geom for a rectangular area object defined by those corner locations. See the discussion of rects in the SQL Example: Miscellaneous SQL Functions topic.

GeomMakeRectDiagonal(<valuex2>, <valuex2>) : <geom>

Takes a pair of x2 values that define diagonally opposite corners of a rectangle and returns a geom for a rectangular area object defined by those corner locations.  See the discussion of rects in the SQL Example: Miscellaneous SQL Functions topic.

GeomMakeSegment(<valuex2>, <valuex2>) : <geom>

Takes a pair of x2 values and returns a line geom consisting of a straight line segment between those two locations.

GeomMakeSegment3(<valuex3>, <valuex3>) : <geom>

Takes a pair of x3 values and returns a 3D line geom consisting of a straight line segment between those two 3D locations.

GeomMakeTriangle(<valuex2>, <valuex2>, <valuex2>) : <geom>

Takes three x2 values that define the corners of a triangle and returns a geom for a triangular area object defined by those corner locations.

GeomMakeTriangle3(<valuex3>, <valuex3>, <valuex3>) : <geom>

Takes three x3 values that define the corners of a triangle in 3D and returns a geom for a 3D triangular area object defined by those corner locations.

GeomNormalize(<geom>, <tolerance>) : <geom>

Normalize object metrics by removing redundant coordinates and note the geom has been normalized.   A tolerance of zero means automatic tolerance.

GeomNormalizeTopology(<drawing>, <tolerance>) : <table>

Takes a drawing and returns a table with the drawing's geoms normalized, providing a table with the same fields but with the values in the geom field altered.   A tolerance of zero means automatic tolerance.

GeomOverlayAdjacent(<drawing>, <overlay>, <tolerance>) : <table>

Combines fields between a source drawing and an overlay drawing, finding cases where objects in the overlay are adjacent to objects in the source.  Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows: Every object in the source drawing that is not adjacent to an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.   Every object in the source drawing that is adjacent to one or more objects in the overlay drawing will appear in one or more rows in the table with values for the o_ fields populated from the corresponding object to which it is adjacent.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayAdjacent Function topic.

GeomOverlayAdjacentPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayAdjacent function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayAdjacent function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayAdjacentFilter(<drawing>, <overlay>, <tolerance>): <table>

Takes a source drawing and an overlay drawing, finds all objects in the source drawing that are adjacent to any object in the overlay drawing, and filters the source drawing leaving only objects which are adjacent to at least one object in the overlay drawing. Unlike the result table of GeomOverlayAdjacent, the result table of GeomOverlayAdjacentFilter includes all fields from the source drawing and no fields from the overlay drawing.

 

Result tables returned by GeomOverlayXxxFilter functions contain all indexes from the source table and are writable. It is possible to chain calls to these functions as well as calls to SelectionXxx functions.

 

Example: The following query returns all states touching selected parcels:

 

EXECUTE CALL GeomOverlayTouchingFilter(states, CALL Selection(parcels, TRUE), 0));

GeomOverlayAdjacentFilterPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayAdjacentFilter function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayAdjacentFilter function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayContained(<drawing>, <overlay>, <tolerance>) : <table>

Combines fields between a source drawing and an overlay drawing, finding cases where objects in the overlay are contained by objects in the source. Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows: Every object in the source drawing that does not contain an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.   Every object in the source drawing that does contain one or more objects in the overlay drawing will appear in one or more rows in the table with values for the o_ fields populated from the corresponding object to which it is adjacent.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayAdjacent Function topic for an example of how functions like this are used.

GeomOverlayContainedPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayContained function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayContained function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayContainedFilter(<drawing>, <overlay>, <tolerance>) : <table>

Takes a source drawing and an overlay drawing, finds all objects in the source drawing that are contained by any object in the overlay drawing, and filters the source drawing leaving only objects which are contained by at least one object in the overlay drawing. Unlike the result table of GeomOverlayContained, the result table of GeomOverlayContainedFilter includes all fields from the source drawing and no fields from the overlay drawing.

 

Result tables returned by GeomOverlayXxxFilter functions contain all indexes from the source table and are writable. It is possible to chain calls to these functions as well as calls to SelectionXxx functions.

 

Example: The following query returns all states touching selected parcels:

 

EXECUTE CALL GeomOverlayTouchingFilter(states, CALL Selection(parcels, TRUE), 0));

 

GeomOverlayContainedFilterPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayContainedFilter function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayContainedFilter function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayContaining(<drawing>, <overlay>, <tolerance>) : <table>

Combines fields between a source drawing and an overlay drawing, finding cases where objects in the overlay are containing objects in the source.  Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows: Every object in the source drawing that is not contained by an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.   Every object in the source drawing that is contained by one or more objects in the overlay drawing will appear in one or more rows in the table with values for the o_ fields populated from the corresponding object to which it is adjacent.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayAdjacent Function topic for an example of how functions like this are used.

GeomOverlayContainingPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayContaining function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayContaining function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayContainingFilter(<drawing>, <overlay>, <tolerance>) : <table>

Takes a source drawing and an overlay drawing, finds all objects in the source drawing that contain any object in the overlay drawing, and filters the source drawing leaving only objects which contain at least one object in the overlay drawing. Unlike the result table of GeomOverlayContaining, the result table of GeomOverlayContainingFilter includes all fields from the source drawing and no fields from the overlay drawing.

 

Result tables returned by GeomOverlayXxxFilter functions contain all indexes from the source table and are writable. It is possible to chain calls to these functions as well as calls to SelectionXxx functions.

 

Example: The following query returns all states touching selected parcels:

 

EXECUTE CALL GeomOverlayTouchingFilter(states, CALL Selection(parcels, TRUE), 0));

 

GeomOverlayContainingFilterPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayContainingFilter function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayContainingFilter function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayIntersecting(<drawing>, <overlay>, <tolerance>) : <table>

Combines fields between a source drawing and an overlay drawing, finding cases where objects in the overlay are intersecting objects in the source.  Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows: Every object in the source drawing that is not intersected by an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.   Every object in the source drawing that is intersected by one or more objects in the overlay drawing will appear in one or more rows in the table with values for the o_ fields populated from the corresponding object to which it is adjacent.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayAdjacent Function topic for an example of how functions like this are used.

GeomOverlayIntersectingPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayIntersecting function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayIntersecting function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayIntersectingFilter(<drawing>, <overlay>, <tolerance>) : <table>

Takes a source drawing and an overlay drawing, finds all objects in the source drawing that intersect any object in the overlay drawing, and filters the source drawing leaving only objects which intersect at least one object in the overlay drawing. Unlike the result table of GeomOverlayIntersecting, the result table of GeomOverlayIntersectingFilter includes all fields from the source drawing and no fields from the overlay drawing.

 

Result tables returned by GeomOverlayXxxFilter functions contain all indexes from the source table and are writable. It is possible to chain calls to these functions as well as calls to SelectionXxx functions.

 

Example: The following query returns all states touching selected parcels:

 

EXECUTE CALL GeomOverlayTouchingFilter(states, CALL Selection(parcels, TRUE), 0));

 

GeomOverlayIntersectingFilterPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayIntersectingFilter function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayIntersectingFilter function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayTopologyIdentity(<drawing>, <overlay>, <tolerance>) : <table>

Using the area boundaries of objects in the overlay drawing, slice all objects in the source drawing into regions that are overlapped by objects in the overlay drawing and that are not overlapped by objects in the overlay drawing.  Save all the pieces thus created as geoms into the result table.  Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows for non-intersecting objects: Every region of an object in the source drawing that is not intersected by an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.  

 

  • Rows for intersecting objects: Every region of an object in the source drawing that is intersected by one or more objects in the overlay drawing will appear as a single row in the table with s_ fields and o_ fields populated by the respective objects from the source and overlay drawings that intersected.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayTopologyUnion Function topic for an example of how functions like this are used.

GeomOverlayTopologyIdentityPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayTopologyIdentity function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayTopologyIdentity function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayTopologyIntersect(<drawing>, <overlay>, <tolerance>) : <table>

Locate regions of intersection and save them into the results table.  Slices all objects in each drawing with the area boundaries of objects in the other drawing and then places geoms for all regions of intersection, discarding duplicates, into the result table.  Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows:  Each region of intersection will appear as a row in the table with s_ fields and o_ fields populated by the respective objects from the source and overlay drawings that intersected.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.  

 

See the SQL Example: GeomOverlayTopologyUnion Function topic for an example of how functions like this are used.

GeomOverlayTopologyIntersectPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayTopologyIntersect function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayTopologyIntersect function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayTopologyUnion(<drawing>, <overlay>, <tolerance>) : <table>

Slices all objects in each drawing with the area boundaries of objects in the other drawing and then places geoms for all pieces, discarding duplicates, into the result table.   Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows for non-intersecting objects: Every object in the source drawing that is not intersected by an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.  Every object in the overlay drawing that is not intersected by an object in the source drawing will appear as a row in the table with values for the s_ fields set to NULL.   

 

  • Rows for intersecting objects: Every object in the source drawing that is intersected by one or more objects in the overlay drawing will appear as a single row in the table with values for the o_ fields set to NULL but will have the geom altered to remove all regions of intersection from the object.  Each region of intersection will appear as a row in the table with s_ fields and o_ fields populated by the respective objects from the source and overlay drawings that intersected.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayTopologyUnion Function topic for an example of how functions like this are used.

GeomOverlayTopologyUnionPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayTopologyUnion function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayTopologyUnion function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayTopologyUpdate(<drawing>, <overlay>, <tolerance>) : <table>

Keep all objects in the overlay drawing.  In the source drawing cut out and discard any portions of objects in the source drawing that intersect with objects in the overlay drawing and leave the remaining portions.  Place geoms for all objects in the overlay drawing plus non-intersecting portions of objects in the source drawing into the result table.  Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows for non-intersecting objects: Every object in the overlay drawing will appear as a row in the table with values for the s_ fields set to NULL.   Every object in the source drawing that is not intersected by an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.  

 

  • Rows for intersecting objects: Every object in the source drawing that is intersected by one or more objects in the overlay drawing will appear as a single row in the table with values for the o_ fields set to NULL but will have the geom altered to remove all regions of intersection from the object.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayTopologyUnion Function topic for an example of how functions like this are used.

GeomOverlayTopologyUpdatePar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayTopologyUpdate function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayTopologyUpdate function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayTouching(<drawing>, <overlay>, <tolerance>) : <table>

Combines fields between a source drawing and an overlay drawing, finding cases where objects in the overlay are touching objects in the source.  Given a drawing and an overlay drawing, returns a table with the following characteristics:

 

  • Columns: The returned table will contain all fields from the source drawing and all fields from the overlay drawing.  Fields from the source drawing will have their names prefixed with s_ for source.  Fields from the overlay drawing will have their names prefixed with o_ for overlay.  

 

  • Rows: Every object in the source drawing that is not touched by an object in the overlay drawing will appear as a row in the table with values for the o_ fields set to NULL.   Every object in the source drawing that is touched by one or more objects in the overlay drawing will appear in one or more rows in the table with values for the o_ fields populated from the corresponding object to which it is adjacent.

 

A tolerance of zero means automatic tolerance. The table supports all indexes of the source drawing. The overlay is performed in the coordinate system of the source drawing; objects in the overlay drawing are automatically converted to that coordinate system as necessary.   We can use the table created by this function as desired in subsequent operations, for example, creating a drawing via a query that uses aggregates.

 

See the SQL Example: GeomOverlayAdjacent Function topic for an example of how functions like this are used.

GeomOverlayTouchingPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayTouching function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayTouching function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomOverlayTouchingFilter(<drawing>, <overlay>, <tolerance>) : <table>

Takes a source drawing and an overlay drawing, finds all objects in the source drawing that touches any object in the overlay drawing, and filters the source drawing leaving only objects which touch at least one object in the overlay drawing. Unlike the result table of GeomOverlayTouching, the result table of GeomOverlayTouchingFilter includes all fields from the source drawing and no fields from the overlay drawing.

 

Result tables returned by GeomOverlayXxxFilter functions contain all indexes from the source table and are writable. It is possible to chain calls to these functions as well as calls to SelectionXxx functions.

 

Example: The following query returns all states touching selected parcels:

 

EXECUTE CALL GeomOverlayTouchingFilter(states, CALL Selection(parcels, TRUE), 0));

 

GeomOverlayTouchingFilterPar(<drawing>, <overlay>, <tolerance>, <config>) : <table>

A parallel form of the GeomOverlayTouchingFilter function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomOverlayTouchingFilter function will be executed. Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomRemoveCurves(<geom>) : <geom>

Returns a geom where each curved segment of an area or line object in the source geom has been replaced with a single straight segment.   Geoms without curved segments are unchanged.

GeomRemoveZ(<geom>) : <geom>

Takes a geom and returns the same geom without Z values. Geoms without Z values are left unchanged. For geoms with Z values curves are replaced with straight line segments, because 3D curves can not be used with a 2D geom.

 

To test if a geom has a Z value, use GeomHasZ. To set the Z values for all coordinates of a geom to a specified value, use GeomSetZ.    To read the Z value of the first coordinate of a geom, use

 

 VectorValue(GeomCoordXYZ([Geom],0),2)

GeomReverseLine(<geom>): <geom>

Takes a geom for a line and reverses the order of coordinates defining the line.  Preserves curvilinear segments and Z values.

GeomRotate(<geom>, <centerx2>, <angle>) : <geom>

Takes a geom, a rotation center as an x2 vector value, a rotation angle in degrees, and returns a rotated geom. The rotation direction is counterclockwise. Z values are preserved but curves are replaced with straight line segments.  

GeomScale(<geom>, <scalex2>): <geom>

A version of GeomScaleShift with shift set to 0 for both X and Y.  Takes a geom, an x2 vector for scale values in X and Y direction, and returns a geom with no shift and with those scale values applied.   Z values are preserved and 2D curvilinear segments are preserved, but 3D curvilinear segments  are replaced with 3D straight line segments.

 

Caveat: attempting to apply uneven XY scales to a circular arc will currently not convert it to an ellipse arc, and will instead compose a new circular arc that passes through the scaled ends and the scaled control point. Future builds will address that with a slight rework of curves in geoms.

GeomScaleCentered(<geom>, <scalex2>, <centerx2>) : <geom>

Takes a geom, an x2 vector for scale factor values in X and Y direction, an x2 vector for  X and Y location of a center in the units of the coordinate system used, and returns a geom with the scale applied around the specified center location.   Z values are preserved and 2D curvilinear segments are preserved, but 3D curvilinear segments  are replaced with 3D straight line segments.

 

Caveat: attempting to apply uneven XY scales to a circular arc will currently not convert it to an ellipse arc, and will instead compose a new circular arc that passes through the scaled ends and the scaled control point. Future builds will address that with a slight rework of curves in geoms.

GeomScaleRev(<geom>, <scalex2>): <geom>

An inverse version of GeomScale.  A version of GeomScaleShift with shift set to 0 for both X and Y.  Takes a geom, an x2 vector for scale values in X and Y direction, and returns a geom with no shift and with those scale values applied as 1/scale.  Unscales back to the original scale a geom that previously was rescaled using  GeomScale.  Z values are preserved and 2D curvilinear segments are preserved, but 3D curvilinear segments  are replaced with 3D straight line segments.

 

Caveat: attempting to apply uneven XY scales to a circular arc will currently not convert it to an ellipse arc, and will instead compose a new circular arc that passes through the scaled ends and the scaled control point. Future builds will address that with a slight rework of curves in geoms.

GeomScaleShift(<geom>, <scalex2>, <shiftx2>) : <geom>

Takes a geom, an x2 vector for scale factor values in X and Y direction, an x2 vector for shift values in X and Y direction in the units of the coordinate system used, and returns a geom with those scale and shift values applied.   Z values are preserved and 2D curvilinear segments are preserved, but 3D curvilinear segments  are replaced with 3D straight line segments.

 

Caveat: attempting to apply uneven XY scales to a circular arc will currently not convert it to an ellipse arc, and will instead compose a new circular arc that passes through the scaled ends and the scaled control point. Future builds will address that with a slight rework of curves in geoms.

GeomScaleShiftZ(<geom>, <scale>, <shift>) : <geom>

Takes a geom, a scale factor value in Z direction, a shift value in Z direction in the units of the coordinate system used, and returns a geom with those scale and shift values applied to the Z values. Geoms with no Z values are left unchanged.   3D curvilinear segments  are replaced with 3D straight line segments.

GeomSegmentize(<geom>, <length>) : <geom>

Takes a geom and a length value and returns a geom where each segment is split to parts which are the same length or shorter than the specified length. Point geoms are left unchanged.   Z values are preserved, but curvilinear segments are replaced with straight line segments.

GeomSetZ(<geom>, <z>) : <geom>

Takes a geom and a Z value, and returns the same geom with Z values for all coordinates set to the specified value. Curves are replaced with straight line segments.

 

To test if a geom has a Z value, use GeomHasZ.   To remove all Z values, use GeomRemoveZ.  To read the Z value of the first coordinate of a geom, use

 

VectorValue(GeomCoordXYZ([Geom],0),2)

 

GeomShift(<geom>, <shiftx2>): <geom>

A version of GeomScaleShift with scale set to 1 for both X and Y.  Takes a geom, an x2 vector for shift values in X and Y direction in the units of the coordinate system used, and returns a geom at the same scale with those shift values applied.  Z values are preserved and 2D curvilinear segments are preserved, but 3D curvilinear segments  are replaced with 3D straight line segments.

GeomSmooth(<geom>, <length>) : <geom>

Takes a geom and a length value and returns a geom that removes detail shorter than the specified length by reducing the number of coordinates. Point geoms are left unchanged. Z values are eliminated. Curvilinear are replaced with straight line segments.  

GeomSnapToGrid(<geom>, <stepsx2>) : <geom>

Takes a geom and  an x2 vector for distance values in X and Y direction and returns a geom with coordinates rounded to a rectangular grid with the specified steps. Curvilinear segments are replaced with straight line segments.

GeomSplitToConvex(<area>, <tolerance>) : <areas>

Takes an area geom and decomposes it into convex parts. A tolerance of zero means automatic tolerance.

GeomSplitToConvexPar(<area>, <tolerance>, <config>) : <areas>

A parallel form of the GeomSplitToConvex function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the GeomSplitToConvex function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

GeomToBranches(<geom>) : <table>

Convert branched objects into a table of branches. Takes a geom and returns a table where each record contains a row for each branch of the object in the geom, with fields as follows:

 

  • Branch - index of the branch

  • Value - geom for that branch.

 

Example:

 

SELECT * FROM (

    SELECT SPLIT

      CALL GeomToBranches([Geom])

    FROM [Table]);

 

GeomToCoords(<geom>) : <table>

Converts objects into their coordinates. Takes a geom and returns a table where each record contains a row for each coordinate of the object in the geom, with fields as follows:  

 

  • Branch - index of current branch.
  • Coord - index of current coordinate from the beginning of geom.
  • CoordInBranch - index of current coordinate within current branch.
  • XY - X, Y coordinates as a float64x2 vector.
  • XYZ - X, Y, Z coordinates as a float64x3 vector (NULL if there is no Z).

 

Example:

 

SELECT * FROM (

    SELECT SPLIT

      CALL GeomToCoords([Geom])

    FROM [Table]);

 

GeomToCoordsLineSequence(<line>, <begin>, <end>, <step>): <table>

Given a geom, beginning and end distances and step (similar to ValueSequence), returns a sequence of coordinates at the specified distances on the line.  The step can be positive or negative. For example, using begin = 0, end = 5, and step = 1, the function will return coordinates at 0, 1, 2, 3, 4, 5.  Using begin = 5, end = 0, and step = -1, the function will return coordinates at 5, 4, 3, 2, 1, 0.  Either begin or end can be outside of the line. For example,  using begin = -2, end = 50, and step = 10, the function will return coordinates at 8, 18, 28, 38, 48.  The coordinates are returned as a table with two fields: distance from the start (Value) and coordinate (XY).

GeomToSegments(<geom>) : <table>

Converts objects into their segments. Takes a geom and returns a table where each record contains a row for each segment of the object in the geom, with fields as follows:

 

  • Branch - index of current branch.
  • Coord - index of starting coordinate of the segment from the beginning of geom.
  • CoordInBranch - index of starting coordinate of the segmment within current branch.
  • XY - starting coordinate value of the segment in X, Y coordinates as a float64x2 vector.
  • XYNext - ending coordinate value of the segment in X, Y coordinates as a float64x2 vector.  
  • XYZ - starting coordinate value of the segment in X, Y, Z coordinates as a float64x3 vector  (NULL if there is no Z).  
  • XYZNext - ending coordinate value of the segment in X, Y, Z coordinates as a float64x3 vector  (NULL if there is no Z).
  • Type - segment type: 0 = straight line segment, 1 = circular arc, 2 = ellipsoidal arc, 3 = non-uniform b-spline.

 

Example:

 

SELECT * FROM (

    SELECT SPLIT

      CALL GeomToCoords([Geom])

    FROM [Table]);

 

GeomToShapes(<geom>) : <table>

A shape is a branch of an area that forms an island.  It is also referred to as an individual polygon within a multipolygon object. This function splits area objects into their constituent shapes using OGC rules for doing so.  Use GeomToShapesEsri to split an area into shapes using ESRI rules.  Takes a geom and returns a table where each record contains a row for each shape, with fields as follows:

 

  • Shape - index of the shape within the original multipolygon.  
  • Branch - index of the original starting branch for this shape.
  • BranchCount - number of branches in this shape.
  • Value - the geom.

 

Points and lines are unchanged except that any curved segments in lines are replaced by straight segments.

 

Consider a table that has one object, a branched area that has islands as seen in the drawing below.

 

 

That area overall has five branches which make up three shapes.   Three of those branches are used to create the larger shape (one branch for the outer boundary and two branches for the inner holes) and two of the branches are used to create the islands.

 

SELECT * INTO [Shapes Table]

  FROM (

    SELECT SPLIT

      CALL GeomToShapes([Geom])

    FROM [Drawing Table]);

 

We can run the query above to use the GeomToShapes function to decompose the single area into three objects, one for each constituent shape.

 

The resulting table contains three rows, one for each of the objects that was created by splitting the original area into its constituent three shapes.

 

The first row is for the larger shape that has two holes.   It is the first shape so the Shape value is 0.   Branch is also 0 because this shape was started by the first branch in the original area.    BranchCount is 3 because this shape contains three branches, one branch for the outer boundary and two branches for the inner holes.

 

Shape number 1, the second shape, was Branch number 3 of the original area.  The BranchCount value for this shape is 1 because this shape contains only one branch.

 

Shape number 2, the third shape, was Branch number 4 of the original area.  The BranchCount value for this shape also is 1 because this shape contains only one branch.

 

 

We can add an index to the Shapes Table, to make the table selectable, and then create a drawing from the table.  We open the drawing above.  It looks like the original, except it now shows three objects instead of just one.  We Ctrl-click the middle object to select it.

 

We can see in the drawing's table that Shape number 1, as expected, is the object selected.

 

GeomToShapesEsri(<geom>) : <table>

Exactly like GeomToShapes  except that it decomposes geoms into shapes based on ESRI rules.  To decompose geoms into shapes using OGC rules use GeomToShapes.

GeomTouches(<geom>, <geom>, <tolerance>) : <value>

Given two geoms returns true if they touch. A tolerance of zero means automatic tolerance.   For the definition of touch see the Join topic.

GeomTriangulate(<geom>, <tolerance>) : <areas>

Triangulates objects.  Given lines, areas or multipoints, performs a Delaunay triangulation of the geom coordinates of an object to create triangles as area objects.   The borders of the triangles will be constrained by geom segments, that is, they will not cross segments within the geom.

GeomTriangulatePar(<geom>, <tolerance>. <config>) : <areas>

A parallel form of the GeomTriangulate function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads" and the minimum number of coordinates to allocate for a thread as "batch."  The threads default is 1 and the batch default is 1000. Use ThreadConfig to generate a JSON string with the desired number of threads to see how values such as "threads" and "batch" are encoded in the JSON string used for the <config> value.

GeomTriangulateLines(<geom>, <tolerance>) : <lines>

Triangulates objects.  Given lines, areas or multipoints, performs a Delaunay triangulation of the geom coordinates of an object to create triangles as line objects.   The borders of the triangles will be constrained by geom segments, that is, they will not cross segments within the geom.

GeomTriangulateLinesPar(<geom>, <tolerance>, <config>) : <lines>

A parallel form of the GeomTriangulateLines function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads" and the minimum number of coordinates to allocate for a thread as "batch."  The threads default is 1 and the batch default is 1000.  Use ThreadConfig to generate a JSON string with the desired number of threads to see how values such as "threads" and "batch" are encoded in the JSON string used for the <config> value.

GeomType(<geom>) : <value>

Returns the object type of a geom as a number:   3 - area ; 2 - line; 1 - point

GeomVoronoi(<points>, <marginx2>, <tolerance>) : <areas>

Given a set of points create a Voronoi diagram and return a geom with the Voronoi cells as area objects.  A tolerance of zero means automatic tolerance.    The x2 value for margin gives the X, Y factors by which to increase the bounding box used for clipping infinite regions.

GeomVoronoiPar(<points>, <marginx2>, <tolerance>, <config>) : <lines>

A parallel form of the GeomVoronoi function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads" and the minimum number of coordinates to allocate for a thread as "batch."  The threads default is 1 and the batch default is 1000.  Use ThreadConfig to generate a JSON string with the desired number of threads to see how values such as "threads" and "batch" are encoded in the JSON string used for the <config> value.

GeomVoronoiLines(<points>, <marginx2>, <tolerance>) : <lines>

Given a set of points create a Voronoi diagram and return a geom with the borders of Voronoi cells as line objects.  A tolerance of zero means automatic tolerance.    The x2 value for margin gives the X, Y factors by which to increase the bounding box used for clipping infinite regions.   

GeomVoronoiLinesPar(<points>, <marginx2>, <tolerance>, <config>) : <lines>

A parallel form of the GeomVoronoiLines function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads" and the minimum number of coordinates to allocate for a thread as "batch."  The threads default is 1 and the batch default is 1000.  Use ThreadConfig to generate a JSON string with the desired number of threads to see how values such as "threads" and "batch" are encoded in the JSON string used for the <config> value.

GeomVoronoiPoints(<points>, <marginx2>, <tolerance>) : <points>

Given a set of points create a Voronoi diagram and return a geom with points at the intersections of borders of Voronoi cells as line objects.  A tolerance of zero means automatic tolerance.    The x2 value for margin gives the X, Y factors by which to increase the bounding box used for clipping infinite regions.  

GeomVoronoiPointsPar(<points>, <marginx2>, <tolerance>, <config>) : <points>

A parallel form of the GeomVoronoiPoints function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads" and the minimum number of coordinates to allocate for a thread as "batch."  The threads default is 1 and the batch default is 1000.  Use ThreadConfig to generate a JSON string with the desired number of threads to see how values such as "threads" and "batch" are encoded in the JSON string used for the <config> value.

GeomWithin(<geom>, <geom>, <distance>, <tolerance>) : <value>

Given two geoms and a distance value returns True if the geoms are closer to each other than the specified distance.  A tolerance of zero means automatic tolerance.  

GeomWkb(<geom>) : <wkb>

Provides a way to extract geometry from a Manifold geometry type, a geom, into a well known binary representation of the geometry, WKB.  Given a geom return a WKB binary representation for that object's geometry.

GeomWkt(<geom>) : <wkt>

Provides a way to extract geometry from a Manifold geometry type, a geom, into a well known binary representation of the geometry, WKT.  Given a geom return a WKT text representation for that object's geometry.

Hypot(<x>, <y>) : <value>

The hypotenuse function: Given x and y returns sqrt(x2 +y2).  

J0(<value>) : <value>

A Bessel function of the first kind: given a value x returns the result of the Bessel function J0(x).  

J1(<value>) : <value>

A Bessel function of the first kind: given a value x returns the result of the Bessel function J1(x).  

Jn(<order>, <value>) : <value>

A Bessel function of the nth kind: given a value x returns the result of the Bessel function Jn(x) for Order n.  

Lgamma(<value>) : <value>

Given a value, returns the log-gamma function for the value.  The log-gamma function takes the natural logarithm of the gamma function for the value.

Log(<value>) : <value>

Given a value, returns the base e logarithm (also called the natural logarithm) of the value.

Log10(<value>) : <value>

Given a value, returns the base 10 logarithm (also called the common logarithm) of the value.

Log1p(<value>) : <value>

Given a value x, return Log(x+1) where Log is the base e logarithm (also called the natural logarithm) of the value.

Log2(<value>) : <value>

Given a value, returns the base 2 logarithm (also called the binary logarithm) of the value.

NullIf(<value>, <value>) : <value>

Returns NULL if the first argument is equal to the second argument, otherwise returns the first argument.  If the value of either argument is NULL, returns NULL.

 

Unlike in Oracle and some other databases, NullIf arguments are only evaluated once.   In Oracle, NullIf(x, y) is an alias for CASE WHEN x=y THEN NULL ELSE x END, an expression which might evaluate x twice.

Pow(<base>, <power>) : <value>

Given a base x and a power y returns x^y.

PragmaValue(<pragma>) : <value>

Returns the value of the specified pragma.  

 

PRAGMA ('custom'='abc');

VALUES (PragmaValue('custom'));

 

See the PRAGMA topic.

Rcbrt(<value>) : <value>

The reciprocal cube root.   Also known as the inverse cube root: returns 1 divided by the cube root of the input value.

Round(<value>) : <value>

Returns the input value rounded up or down to the nearest integer.

RoundDecs(<value>, <decimals>) : <value>

Returns the input value rounded up or down to the specified number of decimal positions.

Rsqrt(<value>) : <value>

The reciprocal square root.   Also known as the inverse square root: returns 1 divided by the square root of the input value.

Selection(<table>, <selected>) : <table>

For tables and components based on tables, such as drawings.   Takes the name of a table and a boolean <selected> flag, and returns a table of either selected or unselected records in the table depending on the value of the flag (True for selected, False for unselected).    For drawings, the name of the drawing can be used as the name of the table, or the drawing's table name can be used as the name of the table.   The examples below show both usages.

 

? CALL Selection([Table], True)

 

Generates a results table that shows all selected records in Table.    Suppose we have a drawing named Mexico with some objects in the drawing selected.

 

? CALL Selection([Mexico], True)

 

Generates a results table that shows all selected records in that drawing's table.

 

Expert Commentary:

 

We liked the ease with which we could not only read, but change the selected drawing objects in Release 8:

 

--SQL

UPDATE [t] SET [f]=[f]+1 WHERE [Selection (I)]

;

 

This did not work for standalone tables not bound to drawings, but for drawing tables, it worked well.

 

Here is how we do that in Manifold Release 9:

 

--SQL

UPDATE CALL Selection([t], TRUE) SET [f]=[f]+1;

 

For example, if we are working with the Products table in the nwind example database and we would like to increase the Units On Order by 10 for all selected records:

 

--SQL

UPDATE CALL Selection([Products], TRUE)

SET [Units On Order] = [Units On Order] + 10;

 

This works for all tables, even those coming from other data sources. The only requirement is that the table must have a btree or btreenull index.

 

We can also do:

 

--SQL

EXECUTE CALL Selection([Table], True);

 

...and edit values for the selected records in the result window.

 

The Selection function greatly simplifies code generated for the transforms.  For example, without this function the code for running Normalize Topology on a selection would have to create temporary components.   With this function, restricting a transform to a selection is a matter of substituting ... FROM [component] with ... FROM CALL Selection([component], True).

 

For an illustrated example, see the SQL Example: Using Selection Query Functions topic.

SelectionWindow(<table>,<windowName>, <layerName>, <selected>) : <table>

For queries and components based on queries, since a selection for a query or component based on a query is dependent upon the specific window.   Can also be used for tables and components based on tables.   Takes the names of a table,   window and layer, and a boolean <selected> flag, and returns a table of either selected or unselected records in the table depending on the value of the flag (True for selected, False for unselected).  The layer name should be an empty string for windows other than map windows.   

 

In the example below the Mexico drawing is open in a drawing window called Mexico, and also participates as a layer in an open map window called Map.  First, the map window:

 

? CALL SelectionWindow([Mexico], 'Map', 'Mexico', True)

 

and second, the drawing window:

 

? CALL SelectionWindow([Mexico Table],'Mexico', '', True)

 

For an illustrated example, see the SQL Example: Using Selection Query Functions topic.

SelectionIsEmpty(<table>) : <value>

Given a table or a component based on a table, such as a drawing, returns True if it does not contain a selection.

 

? SelectionIsEmpty([Mexico Table])

 

For an illustrated example, see the SQL Example: Using Selection Query Functions topic.

SelectionIsEmptyWindow(<table>,

<windowName>, <layerName>) : <value>

For queries and components based on queries, since a selection for a query or component based on a query is dependent upon the specific window.   Can also be used for tables and components based on tables.   Takes the names of a table,  window and layer, and returns True if it does not contain a selection.

 

? SelectionIsEmptyWindow([Mexico], 'Map', 'Mexico')

 

In the above a map window called Map shows a drawing called Mexico in a layer called Mexico.

SelectionIsInverted(<table>) : <value>

Given a table or a component based on a table, such as a drawing, returns True if a selection lists selected records and False if it lists unselected records.

 

? SelectionIsInverted([Mexico Table])

 

For an illustrated example, see the SQL Example: Using Selection Query Functions topic.

SelectionIsInvertedWindow(<table>,

<windowName>, <layerName>) : <value>

For queries and components based on queries, since a selection for a query or component based on a query is dependent upon the specific window.   Can also be used for tables and components based on tables.   Takes the names of a table,  window and layer, and returns True if a selection lists selected records and False if it lists unselected records.

 

? SelectionIsInvertedWindow([Mexico], 'Map', 'Mexico')

 

In the above a map window called Map shows a drawing called Mexico in a layer called Mexico.

SelectionKeys(<table>) : <table>

Given a table or a component based on a table, such as a drawing, returns a table of key field values for selected records.

 

? CALL SelectionKeys([Mexico Table])

 

In the above if Mexico Table uses a mfd_id field as a key field, and records with mfd_id of 3 and mfd_id of 5 are selected, the results table will have one column named mfd_id with two records in it, one with a value of 3 in that column and one with a value of 5.

 

For an illustrated example, see the SQL Example: Using Selection Query Functions topic.

SelectionKeysWindow(<table>,

<windowName>, <layerName>) :  <table>

For queries and components based on queries, since a selection for a query or component based on a query is dependent upon the specific window.   Can also be used for tables and components based on tables.   Takes the names of a table,  window and layer, and returns a table of key field values for selected records.

 

? CALL SelectionKeysWindow([Mexico], 'Map', 'Mexico')

 

In the above a map window called Map shows a drawing called Mexico in a layer called Mexico.  

 

If the drawing's table uses a mfd_id field as a key field, and records with mfd_id of 3 and mfd_id of 5 are selected, the results table will have one column named mfd_id with two records in it, one with a value of 3 in that column and one with a value of 5.

Sign(<value>) : <value>

Given a value returns the sign of the value as -1, 0 or 1 for negative numbers, zero, or positive numbers.

 

? Sign(-23)

 

? Sign(0)

 

? Sign(9)

 

Sin(<radians>) : <value>

Given a value in radians return the sine of the value.  

Sinh(<radians>) : <value>

Given a value in radians return the hyperbolic sine of   the value.  

Sqrt(<value>) : <value>

Given a value returns the square root of the value.

StringBinaryBase64(<string) : <value>

Given a base64-encoded string that encodes a binary value, returns the binary value.

StringBinaryHex(<string>) : <value>

Given a hexadecimal-encoded string that encodes a binary value, returns the binary value.   

StringCompareCollate(<string>, <string>, <collate-code>) : <value>

Same as Compare but compares two strings using the specified collation.  

 

Returns -1 if the first string is less than the second string, 1 if the first string is greater than the second string and 0 if the first and second strings are the same.   

 

In the examples that follow 928 is the collation code for en-US (US English) that is case sensitive.   930 is the collation code for en-US where case does not matter.

 

? StringCompareCollate('John','john', 928)

 

returns 1, meaning the first string is greater than the second string.  

 

? StringCompareCollate('John','john', 930)

 

returns 0, meaning the two strings are the same (as they are if case does not matter).

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringCompareKeyCollate(<string>, <collate-code>) : <value>

Given a string and a specified collation returns a binary representation of the text using the specified collation.  The produced key can be compared to keys for other strings with the same collation, and such comparisons will yield the same result as if the comparison was done using StringCompareCollate(). However, comparing binary keys is usually much faster than comparing strings using a given collation.

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringContains(<string>, <substring>) : <boolean>

Given a string and a substring returns True if the string contains the substring using case-sensitive comparison.

 

? StringContains('Long John Silver', 'john')

 

returns 0 for False,  because when case matters john does not occur in the first string.

 

? StringContains('Long John Silver', 'John')

 

returns 1 for True.

StringContainsCollate(<string>, <substring>, <collate-code>) : <boolean>

Given a string, a substring and a collation returns True if the string contains the substring using the rules of the specified collation.   

 

In the examples that follow 928 is the collation code for en-US (US English) that is case sensitive.   930 is the collation code for en-US where case does not matter.

 

? StringContainsCollate('Long John Silver', 'john', 928)

 

returns 0 for False,  because if case matters john does not occur in the first string.

 

? StringContainsCollate('Long John Silver', 'john', 930)

 

returns 1 for True,  because if case does not matter john occurs as the second word in the first string.

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringDecrypt(<encrypted>, <key>) : <string>

Given an encrypted string produced by StringEncrypt and the key used for encryption,  returns the decrypted original string.  

StringEncrypt(<string>, <key>) : <encrypted>

Given a string and a second string to use as an encryption key, utilizes an AES256 encryption mechanism to return an encrypted string.    The encrypted string may later be decrypted using StringEncrypt.  

StringEndsWith(<string>, <substring>) : <boolean>

Given a string and a substring returns True if the string ends with the substring using case-sensitive comparison. See the StringContains function for similar examples.

StringEndsWithCollate(<string>, <substring>, <collate-code>) : <boolean>

Given a string, a substring and a collation returns True if the string ends with the substring using the rules of the specified collation.    See the StringContainsCollate function for similar examples.

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringEscape(<string>, <escape>) : <string>

Used to create strings that require character escaping to get around syntax rules for how some characters have special meaning in the syntax of functions or queries.   Given a first string and a second, escape string that specifies how a designated escape character is to be used to escape other characters, returns a string where the characters in the first string have been escaped as specified by the escape string.

 

? StringEscape('abc \'def\' ghi', '\\\'')

 

Returns:

 

abc \'def\' ghi

 

StringEscapeEncode(<string>, <escape>, <escapeUnprintable>) : <string>

 

StringEscapeJson(<string>) : <string>

Takes a JSON string and automatically adds character escaping so it can safely be used in functions or queries.

StringFind(<string>, <substring>) : <position>

Given a string and a substring returns the position, beginning with 0,  in the string of the first character of the substring if the string contains the substring using case-sensitive comparison.   If the string does not contain the substring return -1.

StringFindCollate(<string>, <substring>, <collate-code>) : <position>

Given a string, a substring and a collation returns the position, beginning with 0,  in the string of the first character of the substring if the string contains the substring using the rules of the specified collation.   If the string does not contain the substring return -1.

 

In the examples that follow 928 is the collation code for en-US (US English) that is case sensitive.   930 is the collation code for en-US where case does not matter.

 

? StringFindCollate('Long John Silver','john', 928)

 

returns -1 because if case matters john does not occur in the first string.

 

? StringFindCollate('Long John Silver','john', 930)

 

returns 5 because if case does not matter the substring john begins at the sixth character in the first string.  

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.  

StringFindNth(<string>, <substring>, <occurrence>) : <position>

Given a string, a substring and an <occurrence> number, n, (zero based counting, with the first <occurrence> being 0, the second being 1 and so on), returns the number of the character position in the text, also zero based, where the substring matches the nth time using case-sensitive comparison.   If not found at the specified nth position return -1.

StringFindNthCollate(<string>, <substring>, <occurrence>, <collate-code>) : <position>

Given a string, a substring and an <occurrence> number, n, (zero based counting, with the first <occurrence> being 0, the second being 1 and so on) and a collation, returns the number of the character position in the text, also zero based, where the substring matches the nth time using the rules of the specified collation.   If not found at the specified nth position return -1.

 

In the examples that follow 930 is the collation code for en-US (US English) that is not case sensitive.

 

? StringFindNthCollate('Long John Silver','L', 1, 930)

 

returns 12 because if case does not matter the second instance (indicated by 1 in zero based counting) of the substring 'L' occurs at the thirteenth character (indicated by 12 in zero based counting).

 

? StringFindNthCollate('Long John Silver','L', 2, 930)

 

returns -1 because there is no third instance of the substring 'L'.   

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringGmlCoordSystem(<gml>) : <system>

 

Given a GML string return a string reporting the coordinate system specified within that GML string.  

StringGmlGeom(<gml>) : <geom>

Convert GML geometry into a Manifold geom:  Given a GML string return a geom that contains the geometry specified in the GML string.

StringJsonBoolean(<json>, <name>, <strict>) : <value>

Extract a boolean value from a named JSON boolean entity.  Given a JSON string find the specified named entity if it exists and if it has a boolean value return that value.  If the named entity does not exist or if it has not been assigned a boolean value, return NULL.   The <strict> option when True requires a boolean value and rejects string representations such as "true".   When False, any other representations for the boolean value, such as string representations, are accepted.  

 

In the following examples a JSON string has two named entities that are intended as booleans: roads and canals.  In the case of the roads entity the boolean value of true  is specified using a boolean, that is just the word true or false not enclosed in quotes.   In the case of the canals entity the boolean value of false is specified using a string, that is, text enclosed in double quote " characters.

 

? StringJsonBoolean('{ "roads": true, "canals": "false" }', 'roads', true)

 

When the <strict> option is true, the above expression returns:

 

boolean: 1

 

? StringJsonBoolean('{ "roads": true, "canals": "false" }', 'canals', true)

 

When the <strict> option is true, the above expression returns:

 

boolean: <NULL>

 

The NULL was returned because a strict requirement that rejects any non-boolean representations leaves the canals entity with no value.   The function only returns a boolean value if the named entity exists and also has a boolean value.

 

? StringJsonBoolean('{ "roads": true, "canals": "false" }', 'roads', true)

 

When the <strict> option is false, the above expression returns:

 

boolean: 1

 

? StringJsonBoolean('{ "roads": true, "canals": "false" }', 'canals', true)

 

When the <strict> option is false, the above expression returns:

 

boolean: 0

 

StringJsonGeoCoordSystem(<json>) : <system>

Extract the coordinate system from a GeoJSON string. Given a GeoJSON  string return a string reporting the coordinate system specified within that GeoJSON  string.  

StringJsonGeoGeom(<json>) : <geom>

Convert GeoJSON geometry into a Manifold geom:  Given a GeoJSON string return a geom that contains the geometry specified in the GeoJSON string.

StringJsonNumber(<json>, <name>, <strict>) : <value>

Extract a numeric value from a named JSON boolean entity.  Given a JSON string find the specified named entity if it exists and if it has a numeric value return that value.  If the named entity does not exist or if it has not been assigned a numeric value, return NULL.   The <strict> option when True requires a numeric value and rejects string representations such as "true".   When False, any other representations for the numeric value, such as string representations, are accepted.  

 

See the examples for the StringJsonBoolean function for use of <strict> to require a specific type.

StringJsonObject(<json>, <name>) : <value>

Extract an object as a string value from a named JSON boolean entity.  Given a JSON string find the specified named entity if it exists and if it has an object as a string value return that value.  If the named entity does not exist or if it has not been assigned a string value, return NULL.   

StringJsonTile(<json>, <cx>, <cy>, <channels>, <strict>): <tile>

Takes a JSON string, the number of pixels by X and Y, and the number of channels and parses the string into a tile. The format is the same as used by TileJson. The function also takes a boolean <strict> flag which defines what to do when the number of values in the string is more or less than stated by the  X * Y * channels arguments.   If <strict> is true, the function returns NULL, otherwise if there are more values than implied by the given arguments the function returns a completed tile ignoring the extra values in the string, or there are less values, an incomplete tile padded with invisible pixels.

StringJsonValue(<json>, <name>, <strict>) : <value>

Extract a string value from a named JSON boolean entity.  Given a JSON string find the specified named entity if it exists and if it has a string value return that value.  If the named entity does not exist or if it has not been assigned a string value, return NULL.   The <strict> option when True requires a string value and rejects any other representations.  When False, any other representations for the string value are accepted.  

 

See the examples for the StringJsonBoolean function for use of <strict> to require a specific type.

StringJsonArray(<json>, <name>) : <value>

Extract an array element as a string value from a named JSON boolean entity.  Given a JSON string find the specified named entity if it exists and if it has an array element return that array as a string value.  If the named entity does not exist or if it has not been assigned an array element, return NULL.  

 

The string returned could be parsed with the StringToJsonArrayValues function.

StringLength(<string>) : <length>

Given a string returns the number of characters in the string.

 

? StringLength('Manifold')

 

StringPadEnd(<string>, <length>, <pad>) : <string>

Given a string, a desired length in number of characters and a string to use as padding, return a string truncated or padded at the end to the desired length as follows:

 

  • If the desired length is less than the length of the original string, truncate the original string (cutting characters off the end) to the desired length and return.
  • If the desired length is greater than the length of the original string, add characters from the padding string to the end of the original string, repeating the padding string as necessary, to fill out the desired length.

 

? StringPadEnd('Sonora', 4, 'Radian')

 

Returns:

 

Sono

 

Example:

 

? StringPadEnd('Sonora', 20, 'Radian')

 

Returns:

 

SonoraRadianRadianRa

 

Example:

 

? StringPadEnd('Sonora', 20, '.')

 

Returns:

 

Sonora..............

 

 

StringPadStart(<string>, <length>, <pad>) : <string>

Given a string, a desired length in number of characters and a string to use as padding, return a string truncated or padded at the beginning to the desired length as follows:

 

  • If the desired length is less than the length of the original string, truncate the original string (cutting characters off the end) to the desired length and return.
  • If the desired length is greater than the length of the original string, add characters from the padding string to the beginning of the original string, repeating the padding string as necessary, to fill out the desired length.

 

? StringPadStart('Sonora', 4, 'Radian')

 

Returns:

 

Sono

 

Example:

 

? StringPadStart('Sonora', 20, 'Radian')

 

Returns:

 

RadianRadianRaSonora

 

Example:

 

? StringPadStart('Sonora', 20, '.')

 

Returns:

 

..............Sonora

 

StringRegexpCount(<string>, <regexp>, <flags>) : <matches>

Given a string, a  regular expression pattern and a flag to use case or to not use case, returns the number of matches to that regular expression found within the string.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.  

 

? StringRegexpCount('Netherlands', 'n', 'c')

 

Returns 1 for the single lower case n character in the string.

 

? StringRegexpCount('Netherlands', 'n', 'i')

 

Returns 2 since if case is ignored both the upper case N and the lower case n match the regular expression 'n'.

StringRegexpFind(<string>, <regexp>, <flags>) : <position>

Given a string, a  regular expression pattern and a flag to use case or to not use case, returns the index (zero based counting) to the position of the first occurrence of that regular expression found within the string and returns -1 if no match is found.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.  

 

? StringRegexpFind('Netherlands', 'n', 'c')

 

Returns 8 (meaning the 9th character) for the single lower case n character in the string which occurs as the ninth character.  

 

? StringRegexpFind('Netherlands', 'n', 'i')

 

Returns 0 (meaning the 1st character) since if case is ignored the upper case N at the first character position matches the regular expression 'n'.

StringRegexpFindNth(<string>, <regexp>, <occurrence>, <flags>) : <position>

Given a string, a  regular expression pattern, an occurrence number n (zero based counting) and a flag to use case or to not use case, returns the index (zero based counting) to the position of the nth occurrence of that regular expression found within the string and returns -1 if no match is found.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.  

 

? StringRegexpFindNth('Netherlands', 'n', 1, 'i')

 

Returns 8 (meaning the 9th character) since if case is ignored the lower case n at the ninth character position is the second occurrence (in zero based counting 1 means the 2nd occurrence) of a match to the regular expression 'n'.

StringRegexpMatches(<string>, <regexp>, <flags>) : <boolean>

Given a string, a  regular expression pattern and a flag to use case or to not use case, returns True if the string exactly matches the regular expression and 0 for False otherwise.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.   This function is used instead of "LIKEX" query operators found in some query engines.

 

? StringRegexpMatches('Netherlands', 'n.*', 'c')

 

Returns 0 (meaning False) since the string does not begin with a lower case n character.

 

? StringRegexpMatches('Netherlands', 'n.*', 'i')

 

Returns 1 (meaning True) since if case is ignored the upper case N at the first character position matches the regular expression 'n*', that is, text which begins with the letter n or N and then has zero or more of any characters following.

StringRegexpReplace(<string>, <regexp>, <target>, <flags>) : <string>

Given a string, a  regular expression pattern, a target replacement string and a flag to use case or to not use case, returns a string where all substrings of characters that match the regular expression have been replaced by the target replacement string.  If no matches are found returns the original string.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.  

 

? StringRegexpReplace('Netherlands', 'n', 'y', 'i')

 

Returns:

 

yetherlayds

 

Example:

 

? StringRegexpReplace('Netherlands', 'n', 'y', 'c')

 

Returns:

 

Netherlayds

 

Example:

 

? StringRegexpReplace('Netherlands', 'n.th.r', 'Upper', 'i')

 

Returns:

 

Upperlands

 

StringRegexpReplaceNth(<string>, <regexp>, <target>, <occurrence>, <flags>) : <string>

Given a string, a  regular expression pattern, an occurrence number n (zero based counting) and a flag to use case or to not use case,returns a string where the nth  substring of characters that match the regular expression has been replaced by the target replacement string.  If no matches are found returns the original string.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.  

 

? StringRegexpReplaceNth('Mississippi', 's', 't', 0, 'c')

 

Returns:

 

Mitsissippi

 

Example:

 

? StringRegexpReplaceNth('Mississippi', 'S', 't', 3, 'i')

 

Returns:

 

Missistippi

 

Example:

 

? StringRegexpReplaceNth('Mississippi', 'ss', 'tt', 1, 'c')

 

Returns:

 

Missittippi

 

StringRegexpSubstring(<string>, <regexp>, <flags>) : <string>

Given a string, a  regular expression pattern and a flag  to use case or to not use case, returns the first substring found that matches the regular expression within the string and returns an empty string if no match is found.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.  

 

? StringRegexpSubstring('Netherlands', 'n.*l', 'i')

 

Returns:

 

Netherl

 

StringRegexpSubstringNth(<string>, <regexp>, <occurrence>, <flags>) : <string>

Given a string, a  regular expression pattern, an occurrence number n (zero based counting) and a flag  to use case or to not use case, returns the nth substring found that matches the regular expression within the string and returns an empty string if no match is found.  The <flag> is not optional and must be either 'i' to ignore case or 'c' to use case.  

 

? StringRegexpSubstringNth('Netherlands', 'n..', 1, 'i')

 

Returns:

 

nds

 

Since the <occurrence> argument of 1 means the second occurrence (zero based counting) of the character n followed by two other characters, case insensitive.

StringReplace(<string>, <source>, <target>) : <string>

Given a string, a source string and a target string, return a modified string with all occurrences of the source string, using case-sensitive comparison, replaced by the target string.   If no instances of the source string are found, returns the original string.   

 

? StringReplace('Long John Silver','Long', 'Short')

 

StringReplaceCollate(<string>, <source>, <target>, <collate-code>) : <string>

Given a string, a source string, a target string and a collation return a modified string with all occurrences of the source string, using the rules of the specified collation,  replaced by the target string.   If no instances of the source string are found, returns the original string.   

 

In the example that follows 930 is the collation code for en-US (US English) that is not case sensitive.

 

? StringReplaceCollate('Long John Silver','long', 'Short', 930)

 

The above expression returns:

 

nvarchar: Short John Silver

 

Collations are rules that specify how to compare text values.  The CollateCode  function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringReplaceNth(<string>, <source>, <target>, <occurrence>) : <string>

Given a string, a source string, a target string, and an <occurrence> number n (zero based counting, with the first <occurrence> being 0, the second being 1 and so on), return a modified string with the nth occurrence of the source string replaced by the target string.  If the source string is not found at the specified nth position returns the original string.

StringReplaceNthCollate(<string>, <source>, <target>, <occurrence>, <collate-code>) : <string>

Given a string, a source string, a target string, an <occurrence> number, n, (zero based counting, with the first <occurrence> being 0, the second being 1 and so on) and a collation, return a modified string with the nth occurrence of the source string, using the rules of the specified collation,  replaced by the target string.  If the source string is not found at the specified nth position returns the original string.

 

In the examples that follow 930 is the collation code for en-US (US English) that is not case sensitive.

 

? StringReplaceNthCollate('Long John Silver','L', 'X', 1, 930)

 

The above expression returns:

 

nvarchar: Long John SiXver

 

? StringReplaceNthCollate('Long John Silver','L', 'X', 2, 930)

 

The above expression returns the original string since there is no third occurrence of the source string 'L'.

 

Collations are rules that specify how to compare text values.  The CollateCode  function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringReverse(<string>) : <string>

Given a string returns a string with the characters in reverse order.

 

? StringReverse('Netherlands')

 

Returns:

 

sdnalrehteN

 

StringSoundex(<string>) : <string>

Given a string returns the Soundex code for that string.  The Soundex algorithm generates short strings of alphanumeric codes based on how an English word sounds.   English words that are pronounced with similar sounds have the same Soundex codes.   

 

? StringSoundex('Sonora')

 

Returns:

 

S560

 

Example:

 

? StringSoundex('Sanara')

 

Returns:

 

S560

 

Soundex codes may be used to find matches to words entered by users who use inexact spelling.   For example, if we have a table of provinces in Mexico and a user enters Sanara we could use a query to find possible matches:

 

SELECT [NAME] FROM [Mexico Table]

  WHERE StringSoundex('Sanara') = StringSoundex([NAME]);

 

Returns a results table with one record, Sonora, because both of the words Sanara and Sonora have the same Soundex code as far as the English-based Soundex algorithm is concerned.

StringStartsWith(<string>, <substring>) : <boolean>

Given a string and a substring returns True if the string starts with the substring using case-sensitive comparison. See the StringContains function for similar examples.

StringStartsWithCollate(<string>, <substring>, <collate-code>) : <boolean>

Given a string, a substring and a collation returns True if the string starts with the substring using the rules of the specified collation.    See the StringContainsCollate function for similar examples.

 

Collations are rules that specify how to compare text values.  The CollateCode  function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringSubstring(<string>, <start>) : <string>

Given a string and a start position (zero based counting) returns the substring from  the start position to the end of the original string.

 

? StringSubstring('Netherlands', 3)

 

Returns:

 

herlands

 

StringSubstringLen(<string>, <start>, <length>) : <string>

Given a string, start position (zero based counting), and a lengths (zero based counting) returns the substring of the specified length beginning at the start position  of the original string.

 

? StringSubstringLen('Netherlands', 3, 4)

 

Returns:

 

herl

 

To get a sequence of desired characters at the start of a string, we specify a start position of 0, the first character, as well as the length of the desired substring:

 

? StringSubstringLen('Netherlands', 0, 4)

 

Returns:

 

Neth

 

StringToCharacters(<string>) : <table>

Split a string into a table of characters.  Given a string returns a table where each row contains a character in the string.

 

? Call StringToCharacters('Netherlands')

 

Returns:

 

 

StringToJsonObjectValues(<json>) : <table>

Split a JSON string into objects.   Given a JSON string returns a table where each row contains an object string for an object contained in that JSON string.

StringToJsonArrayValues(<json>) : <table>

Split a JSON string into array values.   Given a JSON string returns a table where each row contains an array value for an array contained in that JSON string.

StringToLowerCase(<string>) : <string>

Given a string returns the same string all in lower case.

StringToLowerCaseCollate(<string>, <collate-code>) : <string>

Given a string and a collation returns the same string all in lower case using the rules of the specified collation.  Ignores <useCase> option in the encoded collation since the result is all lower case.

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringToRegexpMatches(<string>, <regexp>, <flags>) : <table>

Given a string, a  regular expression pattern and a flag  to use case or to not use case, returns a table where each row contains a substring found that matches the regular expression within the string.

 

? CALL StringToRegexpMatches('Mississippi', 'i.', 'c')

 

Returns

 

 

StringToTitleCase(<string>) : <string>

Requires Windows 7 or more recent Windows edition.  Given a string returns the same string in title case, converting the initial letter of each word into upper case and converting other characters into lower case, except that words which are already all upper case are left all upper case.

 

? StringToTitleCase('a walk in the park')

 

Returns:  A Walk In The Park

 

? StringToTitleCase('a WALK in the park')

 

Returns:  A WALK In The Park

 

? StringToTitleCase('a waLK iN tHe pARK')

 

Returns:  A Walk In The Park

 

? StringToTitleCase('A WALK IN THE PARK')

 

Returns:  A WALK IN THE PARK

 

To apply title case Manifold uses a Windows system facility, which reckons that a word which is in all capital letters is already in title case.  Strings that consist of all upper case characters therefore will not be modified. To transform such strings into a form where each word is lower case except for an initial capital letter, first  use the StringToLowerCase  function to transform the string into all lower case and then use the StringToTitleCase function.  

 

Contrary to most literary styles used in English, Windows also will capitalize articles, conjunctions and prepositions such as "of" and "the," so this function is best understood as Windows-style title case and not title case as understood in literary circles.

StringToTitleCaseCollate(<string>, <collate-code>) : <string>

Requires Windows 7 or more recent Windows edition.  Given a string and a collation returns the same string in title case using the rules of the specified collation.  Ignores <useCase> option in the encoded collation since the result is title case.  See the StringToTitleCase function for what is reckoned to be Windows-style title case.

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.  

StringToTokens(<string>, <separator>) : <table>

Split a string into substrings bounded by a given separator character.   Given a string and a separator string containing one character (such as a space character), returns a table where each row contains the substrings of the original string that were bounded by the separator.  

 

? CALL StringToTokens('Long John Silver', ' ')

 

Returns:

 

 

StringToUpperCase(<string>) : <string>

Given a string returns the same string all in lower case.

StringToUpperCaseCollate(<string>, <collate-code>) : <string>

Given a string and a collation returns the same string all in upper case using the rules of the specified collation.  Ignores <useCase> option in the encoded collation since the result is all upper case.

 

Collations are rules that specify how to compare text values.  The CollateCode function generates a number for a specific rule that can be used as the <collate-code> argument in functions that use collations.  See the COLLATE topic.

StringTranslate(<string>, <source>, <target>) : <string>

Given a string, a source string and a target string, returns a string where characters in the original string that are found in the  source string have been replaced on a character-by-character basis by the corresponding character in the target string.

 

? StringTranslate('Netherlands', 'abcde', 'xyz12')

 

Returns:

 

N2th2rlxn1s

 

The e characters were replaced by 2, the a character was replaced by x and the d character was replaced by 1.

StringTrim(<string>, <trim>) : <string>

Given a string and a trim string, removes all occurrences, including repeated occurrences, of the trim string at the beginning or the end of the string and returns the trimmed string.  Often used with a trim string of just one character, a ' ' space character, to trim extra spaces from the beginning and end of a string.  Often used to trim other text as well.

 

? StringTrim('"/info/products.shtml"', '"')

 

Returns:

 

/info/products.shtml

 

StringTrimEnd(<string>, <trim>) : <string>

Given a string and a trim string, removes all occurrences, including repeated occurrences, of the trim string at the end of the string and returns the trimmed string.  Often used with a trim string of just one character, a ' ' space character, to trim extra spaces from the end of a string.  Often used to trim other text as well.

 

? StringTrimEnd('<a href="/info/products.shtml">', '">')

 

Returns:

 

<a href="/info/products.shtml

 

StringTrimStart(<string>, <trim>) : <string>

Given a string and a trim string, removes all occurrences, including repeated occurrences, of the trim string at the beginning of the string and returns the trimmed string.  Often used with a trim string of just one character, a ' ' space character, to trim extra spaces from the beginning of a string.  Often used to trim other text as well.

 

? StringTrimStart('<a href="/info/products.shtml', '<a href="')

 

Returns:

 

/info/products.shtml

 

Example, combining the StringTrimStart and StringTrimEnd functions (written as a single line in the Command Window):

 

? StringTrimStart(StringTrimEnd('<a href="/info/products.shtml">', '">'), '<a href="')

 

Returns:

 

/info/products.shtml

 

StringUnescape(<string>, <escape>) : <string>

Remove escaping sequence from strings that use character escaping.   Given a first string and a second, escape string that specifies how a designated escape character sequence is to be used to escape other characters, returns a string where the characters in the first string have had character escaping,  escaped as specified by the escape string, removed.

 

? StringUnescape('abc \'def\' ghi', '\\\'')

 

Returns:

 

abc 'def' ghi

 

StringUnescapeDecode(<string>, <escape>, <escapeUnprintable>) : <string>

 

StringUnescapeJson(<string>) : <string>

Takes a JSON string to which character escaping has been added (such as by the StringEscapeJson function) and removes the character escaping.

StringWktGeom(<wkt>) : <geom>

Convert WKT geometry into a Manifold geom:  Given a WKT string return a geom that contains the geometry specified in the WKT string.

 

? StringWktGeom('POINT(10.687 59.8876)')

 

The expression above returns a geom that contains a point.

SystemCpuCount() : <count>

Returns the number of CPUs in the system.   Multiple CPU cores, including hypercores, are counted as CPUs if treated as CPUs by the operating system.

 

? SystemCpuCount()

 

The function appears in virtually every query automatically created by Edit Query button in the Transform pane, in the line:

 

THREADS SystemCpuCount()

 

The above line takes whatever the SystemCpuCount function returns and sets the number of threads for the query to use to that number.   That tells Manifold to use all CPU cores for the query.  

 

SystemGpgpuCount() : <count>

Returns the number of GPGPU-capable GPUs in the system.   The function reports the number of GPU chips in the system, not the number of processing cores in each.  Use the SystemGpgpus function to look up the name of each GPU, which can then be used on the NVIDIA web site to learn details, such as the number of processing cores, of each GPU.

 

? SystemGpgpuCount()

 

SystemGpgpus() : <table>

Returns a table giving the name of each GPU in the system.  

 

? CALL SystemGpgpus()

 

TableCache(<table>, <writable>): <table>

Takes a table and a <writable> parameter and caches the table's data, allowing either reads or both reads and writes depending on the <writable> parameter. A <writable> parameter of TRUE means the result table is writable.  The result table has all indexes that were in the original table. Writes to the result table update both the original table and the cache.

 

Given the TableCache function, we can:

 

  • Write a SELECT ... WHERE x=y query in Manifold which hits the index on the database, and have that query run fast on the database.  We can then...
  • Wrap the result into a write-through cache using TableCache or TableCacheIndexGeoms.   We can then...
  • Display the result as a drawing and work with it, with any changes to the drawing being seamlessly transported through the cache into the database.

 

Example

 

For a hypothetical connection into SQL Server, we write a query:

 

TABLE CALL TableCache(

 (SELECT * FROM [sqlserver]::[dbo.geom_of_fields]

  WHERE [company_id] = '011900'),

  TRUE -- allows writing through the cache into the database

);

 

Right-click the query in the Project pane, select Create - New Drawing, select the geometry field, specify coordinate system, and click OK.  This creates a drawing from the query.

 

We can now work with the drawing. It will only have objects for the company_id we specified, with filtering for company_id being done in SQL Server, accelerated by any indexes it might have.

 

Opening the drawing will fetch all data for the specified company_id into the cache, with the spatial index built on just the fetched data:.  Therefore,  renders / pans / zooms and other operations in the map window will be fast.

 

The drawing is editable: all changes go through the cache into the database. All this is accomplished without creating any views within SQL Server.

TableCacheIndexGeoms(<table>, <writable>): <table>

The same as TableCache and also adds an RTREE index on each geometry field.

Tan(<radians>) : <value>

Given a value in radians, returns  the tangent of the value.

Tanh(<radians>) : <value>

Given a value in radians, returns  the hyperbolic tangent of the value.

Tgamma(<value>) : <value>

Given a value, returns the gamma function of the value.  

ThreadConfig(<threads>) : <config>

Given a number indicating the number of desired threads, return a JSON string encoding that number of threads as a configuration string for use in parallelized functions that take a <config> parameter to enable setting the number of desired threads.  The default use of ThreadConfig is with SystemCpuCount(), to use all available threads.

 

Specifying a number of threads generates a thread configuration JSON string for the desired number of threads:

 

? ThreadConfig(14)

 

Returns an nvarchar JSON string of

 

{ "threads": "14" }

 

Example: create a set of contours for the given heights using all available threads:

 

EXECUTE CALL TileContourAreasPar([german_alps],

  (VALUES (500), (1000), (1500), (3500)), -- heights

  true, ThreadConfig(SystemCpuCount()));

 

Example: create a set of contours for the given heights using four threads:

 

EXECUTE CALL TileContourAreasPar([german_alps],

  (VALUES (500), (1000), (1500), (3500)), -- heights

  true, ThreadConfig(4));

 

TileAbs(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the absolute value of the input tile pixel values.   Absolute value leaves positive numbers unchanged and converts negative numbers into their positive equivalents.  

TileAcos(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the arc cosine (inverse cosine) of the input tile pixel values.

TileAcosh(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the hyperbolic arc cosine of the input tile pixel values.

TileAsin(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the arc sine (inverse sine) ofthe input tile pixel values.

TileAsinh(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the hyperbolic arc sine of the input tile pixel values.

TileAspect(<tile>, <radius>, <scalex3>) : <tile>

Given a tile value, a radius, and XYZ scales, returns a tile with pixel values set to the aspect in degrees of the surface implied by treating input tile pixel values as heights.  GPU parallelism switches to CPU parallelism at a radius of 9 or greater.

TileAtan(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the arc tangent (inverse tangent) of the input tile pixel values.

TileAtan2(<y>, <x>) : <tile>

Given a tile value returns a tile with pixel values set to the arc tangent (inverse tangent) of the ratio between the DY field and the DX field specified.

TileAtanh(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the hyperbolic arc tangent of  the input tile pixel values.

TileBgrHcy(<tilebgr>) : <tilehcy>

Given a tile value with pixels in BGR color space returns a tile with pixel values in HCY (Hue, Chroma, Luminance) color space. "Luminance" is often referred to as "Y".    This color space is often known as HCL (Hue, Chroma, Luminance).

TileBgrHsi(<tilebgr>) : <tilehsi>

Given a tile value with pixels in BGR color space returns a tile with pixel values in HSI (Hue, Saturation, Intensity) color space.

TileBgrHsl(<tilebgr>) : <tilehsl>

Given a tile value with pixels in BGR color space returns a tile with pixel values in HSL (Hue, Saturation, Lightness) color space.

TileBgrHsv(<tilebgr>) : <tilehsv>

Given a tile value with pixels in BGR color space returns a tile with pixel values in HSV (Hue, Saturation, Value) color space.  Often referred to as HSB (Hue, Saturation, Brightness) color space.

TileCbrt(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to cubic root of the input tile pixel values.

TileCeil(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the rounded up integer value of the input tile pixel values.

TileCeilDecs(<tile>, <decimals>) : <tile>

Given a tile value and the desired number of decimals returns a tile with pixel values set to the integer value rounded up to the specified number of decimals of the input tile pixel values.

TileChannel(<tile>, <channel>) : <tile>

Given a tile value returns a tile with pixel values set to the values in the designated channel of the input tile.

TileChannelCopy(<tile>, <channel>, <tileSource>, <channelSource>): <tile>

Given a source tile and source channel, and a destination tile and destination channel, copies pixel values from the source channel in the source tile into the destination channel in the destination tile.   Source and destination tiles must be the same dimension.  Source and destination pixel data types can be different, with conversion automatically being done on the fly.  

TileChannelCount(<tile>) : <value>

Given a tile value returns the number of channels in the tile.  For example, a tile containing uint8x3 pixel values will have three channels.

TileChannels(<tile>, <value/valuexN>) : <tile>

Rearrange the component parts of a pixel value vector within a tile as directed by an index vector, similar to how the VectorValues function rearranges component parts of a vector value.  The VectorValues function rearranges the component parts of a single vector value.   The TileChannels function rearranges the component parts of all pixel value vectors in the tile.  

 

For example, if a tile is composed of uint8x3 vector values for each pixel where the three parts of the uint8x3 vector represent B, G and R channel values, applying TileChannels function to that tile using an index vector set of {2,1,0} will reshuffle the values so the uint8x3 vector will contain R, G and B channel values.   See the discussion for the VectorValues function.

 

Passing a single value makes TileChannels work like TileChannel, extracting a single channel from potentially multi-channel data. The number of channels in the tile returned by TileChannels does not have to be the same as the  number of channels in the original tile.

 

For example, executing an expression in the Command Window using TileMake to construct an example tile from which we will take a channel:

 

? TileJson(TileChannels(TileMake(3, 3, VectorMakeX3(160, 192, 255)), 1))

nvarchar: [

 192, 192, 192,

 192, 192, 192,

 192, 192, 192

]

 

The above extracts the second channel (Channel 1 in zero-based counting) from a three channel tile.

 

For example, we can add an extra channel not in the original tile:

 

? TileJson(TileChannels(TileMake(3, 3, 255), VectorMakeX4(0, 0, 0, -1)))

nvarchar: [

 255, 255, 255, 0, 255, 255, 255, 0, 255, 255, 255, 0,

 255, 255, 255, 0, 255, 255, 255, 0, 255, 255, 255, 0,

 255, 255, 255, 0, 255, 255, 255, 0, 255, 255, 255, 0

]

 

The above fills the first three channels with the original first channel (Channel 0 in zero-based counting) and then adds an extra channel filled with zeros.

 

See the Example: Rearrange Channels using an Expression topic for an example using TileChannels to change BGR channel order to RGB channel order.

TileChannelsConcat(<tile>, <tileConcat>) : <tile>

 

TileChannelsConcatFill(<tile>, <tileConcat>) : <tile>

Given a tile and a second tile of the same dimensions, concatenates the second tile's channels onto the first tile, returning a tile with concatenated channels up to a total of four channels.  

 

Using the TileChannelsConcat  function, pixels will be visible if they are visible in both of the concatenated tiles.  Using the TileChannelsConcatFill function, pixels will be visible if they are visible in either of the concatenated tiles, and any missing channel values will be filled with zeros.

 

For example, if the first tile called [BG Tile] has uint8x2 values, that is, a vector value with two parts, that represent B and G values for an image, and a second tile called [R Tile] has a single uint8 value for each pixel that represents R values, then:

 

TileChannelsConcat([BG Tile], [R Tile])

 

Returns a tile with pixel values as uint8x3 three part vectors that represent  B, G and R values.

TileClear(<tile>): <tile>

Given a tile, returns a tile with all pixels set to invisible.  

With the focus on the image shown above, in the Transform pane we choose the Expression tab.

We enter the expression:

 

TileClear([Tile])

 

The image disappears.  If in the Layers pane we turn off the background layer, we can see the default checkerboard pattern, since all pixels in the image are now transparent.

TileCompare(<tile>, <tile>) : <tile>

TileCompare compares two tiles pixel by pixel and returns a tile of numeric values as follow: -1 where the pixel of the first tile is less than the pixel of the second tile, 0 where pixels are equal, and 1 where the pixel of the first tile is greater than the pixel of the second tile. The resulting tile can then be multiplied, used as a mask, or for other operations.

TileContourArea(<image>, <heightMin>, <heightMax>) : <geom>

Takes a 1-channel image, minimum height, maximum height and returns a single  contour area for the specified height range. If none of the image pixels is in the specified height range, the function returns a NULL value.

 

Example: create a single contour area:

 

VALUES (TileContourArea([german_alps], 1000, 2000));

 

TileContourAreaPar(<image>, <heightMin>, <heightMax>, <config>): <geom>

A parallel form of the TileContourArea function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileContourArea function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileContourAreas(<image>, <heights>, <decompose>): <table>

Takes a 1-channel image and a set of heights specified as a table, and returns a table of contour areas with fields for: Geom, ValueMin, and ValueMax. The set of heights does not have to be sorted and may contain duplicates, which will be ignored. For N unique heights, the returned table contains N+1 records: the area below the smallest height, N-1 areas between subsequent heights, and the  area above the biggest height. Some of the geoms in the returned table might be NULL values. The returned areas cover the entire image.  The decompose argument is true or false: when true, the result is decomposed into multiple objects when a single object would exceed 64 million coordinates.

TileContourAreasPar(<image>, <heights>, <decompose>, <config>)

A parallel form of the TileContourAreas function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileContourAreas function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

 

Example: create a set of contours for the given heights using all available threads:

 

EXECUTE CALL TileContourAreasPar([german_alps],

  (VALUES (500), (1000), (1500), (3500)), -- heights

  true, ThreadConfig(SystemCpuCount()));

 

Example: create a set of contours for the given heights using four threads:

 

EXECUTE CALL TileContourAreasPar([german_alps],

  (VALUES (500), (1000), (1500), (3500)), -- heights

  true, ThreadConfig(4));

 

TileContourLine(<image>, <height>): <geom>

Takes a 1-channel image and height, and returns a single contour line for the specified height. If the specified height is lower or higher than any of the image pixels, the function returns a NULL value.

TileContourLinePar(<image>, <height>, <config>): <geom>

A parallel form of the TileContourLine function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileContourLine function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileContourLines(<image>, <heights>, <decompose>): <table>

Takes a 1-channel image and a set of heights specified as a table, and returns a table of contour lines with fields for: Geom, and Value (height). The set of heights does not have to be sorted and may contain duplicates, which will be ignored. The returned table contains a record for each unique height. Some of the geoms in the returned table might be NULL values.  The decompose argument is true or false: when true, the result is decomposed into multiple objects when a single object would exceed 64 million coordinates.

TileContourLinesPar(<image>, <heights>, <decompose>, <config>): <table>

A parallel form of the TileContourLines function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileContourLines function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileContrast(<tile>, <center>, <power>) : <tile>

Given a tile with single channel values, a center value and an exponent value adjust the contrast of the image.  Tones below the center value will be darkened exponentially and those above will be lightened exponentially using the power argument, to produce values for the returned tile that will give it altered contrast.

TileCos(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to  the input tile pixel values.

TileCosh(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to  the input tile pixel values.

TileCurvGaussian(<tile>, <radius>, <scalex3>) : <tile>

Given a tile value, a radius, and XYZ scales, computes Gaussian curvature.  Gaussian curvature indicates the overall curvature of a surface, if the surfce is positively curved like a dome, negatively curved like a cup, saddle-shaped or not curved. Gaussian curvature at any pixel is the geometric mean of the maximum and minimum curvatures that can be found in any given direction from that pixel. High values indicate more curvature along both maximum and minimum curvature directions. GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  See the CalTech article.

TileCurvMean(<tile>, <radius>, <scalex3>) : <tile>

Given a tile value, a radius, and XYZ scales, computes mean curvature.  The mean curvature at any pixel is the arithmetic mean of the maximum and minimum curvatures that can be found in any given direction from that pixel.  High values indicate more curvature along at least one of the maximum and minimum curvature directions.  GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  See the CalTech article.

TileCurvPlan(<tile>, <radius>, <scalex3>) : <tile>

Given a tile value, a radius, and XYZ scales, computes planform curvature. Plan curvature is the curvature of a surface perpendicular to the direction of maximum slope. GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  See the ESRI article.

TileCurvProfile(<tile>, <radius>, <scalex3>) : <tile>

Given a tile value, a radius, and XYZ scales, computes profile curvature. Profile curvature is the curvature of a surface parallel to the direction of maximum slope.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  See the ESRI article.

TileCut(<image>, <valuex2>) : <tile>

Given an image and X and Y values as an x2 vector, returns the tile at the specified X and Y location in the image.   

TileCutBorder(<image>, <valuex2>, <border>) : <tile>

Given an image,  X and Y values as an x2 vector, and a border size, returns the tile at the specified X and Y location in the image with the specified border.  The border size can be negative.  GPU parallelism switches to CPU parallelism at a border size of 9 pixels or more.  Calls to tile functions which use borders of 9 or more pixels automatically dispatch to CPU parallelism, and can freely intermix with calls dispatched to GPU parallelism.

TileCutRect(<image>, <valuex4>) : <tile>

Given an image and the two X,Y corners of a rectangle (Xmin, Ymin and Xmax, Ymax) in the image as an x4 vector, returns the tile at the specified rectangle in the image.

TileDistanceMake(<image>): <distances>

Given a raster, returns a distance buffer computed using shortest Euclidean (straight line) distance that can be used in further calls.

TileDistanceMakePar(<image>, <threads>): <distances>

A parallel form of the TileDistanceMake function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileDistanceMake function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileDistanceMakeSlope(<image>, <slopeMin>, <slopeMax>, <weightMin>, <weightZero>, <weightMax>): <distances>

Given a raster where each pixel value is a slope, and using specified parameters, returns a distance buffer that can be used in further calls, Computed using path distances where pixel costs are generated from slope values based on slope values and the specified parameters, thus allowing paths going downhill to have lower costs.

 

<slopeMin>, <slopeMax> -  Minimum and maximum values for the allowed slopes.  Pixels with slopes equal to or lower than minimum, or equal to or higher than maximum are considered to not be traversable and will be avoided by paths.  Transform templates using this function use -90 and 90 as defaults for minimum and maximum slope values allowed.

 

<weightMin>, <weightZero>, <weightMax> - Costs for minimum slope, zero or flat slope, and maximum slope.  Transform templates using this function use 0, 1, and 2 as defaults for costs for minimum slope, zero slope, and maximum slope respectively.  The default values weight paths going downhill as having lower costs.

TileDistanceMakeSlopePar(<image>, <slopeMin>, <slopeMax>, <weightMin>, <weightZero>, <weightMax>, <threads>): <distances>

A parallel form of the TileDistanceMakeSlope function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileDistanceMakeSlope function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileDistanceMakeWeighted(<image>, <equal>): <distances>

Given a raster and a boolean flag to use equal costs (weights), returns a distance buffer computed using shortest or lowest cost path distance that can be used in further calls. An <equal> flag of TRUE uses equal costs for all pixels, computing shortest paths that avoid missing pixels.  An <equal> flag of FALSE uses values in valid pixels as distance / travel costs, computing lowest cost paths that avoid missing pixels.

TileDistanceMakeWeightedPar(<image>, <equal>, <threads>): <distances>

A parallel form of the TileDistanceMakeWeighted function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileDistanceMakeWeighted function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileDistanceTilesClosest(<distances>, <drawing>): <table>

Given a distance buffer and a drawing with points where points have a Z values, returns a raster with the value of each pixel set to the Z value of the closest point.

TileDistanceTilesClosestPar(<distances>, <drawing>, <threads>): <table>

A parallel form of the TileDistanceTilesClosest function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileDistanceTilesClosest function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileDistanceTilesDirection(<distances>, <drawing>, <type>): <table>

Given a distance buffer, a drawing with points, and a direction type, returns a raster with the value of each pixel set to the direction of the shortest path from the pixel to the closest point. Direction types:

 

  • 0 - Direction to the closest point, in degrees between 0 and 360, Euclidean distances only, the default.
  • 1 - Direction to the next pixel on the shortest path to the closest point, in degrees The direction from each pixel to an adjacent pixel can be only one of eight possible directions, 45, 90, 135, 180, 225, 270, or 315, or 360 degrees,  since adjacent pixels can only be to the left or right, above or below, or at one of four diagonal directions in between.  Direction values will be restricted to those eight values, plus 0 for the pixel coincident with the nearest point. Path distances only.
  • 2 - Direction to the next pixel on the shortest path to the closest point, a quadrant value between 0 and 7, and using -1 when the pixel is coincident with the closest point, path distances only.
  • 3 - Direction to the next pixel on the shortest path to the closest point, a quadrant value between 1 and 8, and using 0 when the pixel is coincident with the closest point, path distances only.

 

TileDistanceTilesDirectionPar(<distances>, <drawing>, <type>, <threads>): <table>

A parallel form of the TileDistanceTilesDirection function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileDistanceTilesDirection function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileDistanceTilesLength(<distances>, <drawing>): <table>

Given a distance buffer, and a drawing with points, returns a raster with the value of each pixel set to the distance from the pixel to the closest point.

TileDistanceTilesLengthPar(<distances>, <drawing>, <threads>): <table>

A parallel form of the TileDistanceTilesLength function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileDistanceTilesLength function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileErf(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the error function (also called erf(z) ) of the input tile pixel values.

TileErfc(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the complementary error function (also called erfc(z) ) of the input tile pixel values.

TileExp(<tile>) : <tile>

The exponential function: Given a tile value returns a tile with pixel values set to e to the power of the input tile pixel values.

TileExp10(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to 10 to the power of the input tile pixel values.

TileExp2(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to 2 to the power of the input tile pixel values.

TileExpm1(<tile>) : <tile>

Given a tile value with pixel values of x, returns a tile with pixel values set to e^x-1.

TileFill(<tile>, <value>) : <tile>

Given a tile value and a pixel value returns a tile with all pixel values set to the specified pixel value.  The function can accept xN values. TileFill keeps the original tile data type.

TileFillBaseLevel(<image>): <table>

Given an image, returns a table (filling the image's table) with tiles for all image tiles within the image rect (rectangular extent), and adding NULL tiles for any missing records (tiles) in the image.

Consider an example using the small image above.

The table for the image has only four records, each record containing a tile.

We select two of the records and delete them.

The table now has only two records, and is missing two records that are required to fill in the image's rect (rectangular extent).

The image window updates with regions of the image where tiles are missing not being rendered.   The message warns us intermediate levels are now out of date.

 

We run the following SQL in the Command Window:

 

TABLE CALL TileFillBaseLevel([Bronze]);

 

Immediately two new records are added to the table, providing NULL values for the missing tiles.  The image is not complete, of course, but the table has records for all X,Y tile positions that are required to fill in the image's rect.

TileFillMissing(<tile>, <value>): <tile>

Given a tile value and a pixel value returns a tile with all missing pixel values set to the specified pixel value and makes them visible. The function can accept xN values. Keeps the original tile data type.  

TileFillMissingCopy(<tile>, <tileBack>): <tile>

Given a tile and a background tile with the same tile sizes, returns a tile with pixels from the first tile where invisible pixels in the first tile have been replaced by corresponding pixels from the background tile.  Keeps the original tile data type. Does nothing if the tile sizes are not the same.

TileFillMissingNearest(<tile>, <radius>): <tile>

Given a tile value and a pixel value returns a tile with all missing pixel values set to the first found visible pixel value within the specified radius. The function can accept xN values. Keeps the original tile data type. 

TileFillSinks(<image>, <fillHeight>, <fillFlow>): <table>

Takes a 1-channel image, the fill height value, the fill flow value, and returns an image with filled sinks, as follows:

  

  • If both fill height and fill flow are negative or zero, the image is left unchanged.

  • If fill height is positive and fill flow is negative or zero, sinks are filled based solely on height, equivalent to the depth of the sink.

  • If fill height is negative or zero and fill flow is positive, sinks are filled based solely on flow, equivalent to the area of the sink.  

  • If both fill height and fill flow are positive, sinks are filled based on both height and flow.

 

See illustrations and examples in the Watershed Prepare: Filling Sinks  topic.

TileFillSinksPar(<image>, <deltaMin>, <flowMin>, <config>): <table>

A parallel form of the TileFillSinks function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileFillSinks function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileFilter(<tile>, <radius>, <filter>): <tile>

Takes an input tile, a radius and a tile with filter coefficients, and performs a linear filter. This is a generalization of TileFilterDefBlur and similar functions, which imply specific ways to create the filter tile.  The function produces missing pixels if the filter shape covers no valid pixels.  GPU parallelism switches to CPU parallelism at a radius of 9 or greater.

TileFilterCount(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, counts the number of non-NULL pixel values with non-zero weights in the filter.   The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  

TileFilterDefCircle(<radius>, <center>): <tile>

Given a radius and center, produce a filter definition matrix to pass to TileFilter.    Applies a circle-shaped linear filter of specified radius.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value compared to other pixels in the array.  

TileFilterDefCross(<radius>, <center>) : <tile>

Given a radius and center, produce a filter definition matrix to pass to TileFilter.    Applies a cross-shaped linear filter of specified radius.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value compared to other pixels in the array. 

TileFilterDefDirection(<radius>, <center>, <angle>) : <tile>

Given a radius, center and angle in radians, produce a filter definition matrix to pass to TileFilter.  Produces a blur effect in the direction specified.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value in averaging compared to other pixels in the array. 

TileFilterDefEdges(<radius>, <center>) : <tile>

Given a radius and center, produce a filter definition matrix to pass to TileFilter.    Detects edges in an image using a Laplacian of Gaussian filter shape, normed to the center value.   The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value compared to other pixels in the array.  

TileFilterDefEdgesDirection(<radius>, <center>, <angle>) : <tile>

Given a radius and center, produce a filter definition matrix to pass to TileFilter.   Detects edges in an image using a Laplacian of Gaussian filter shape, normed to the center value.   The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value compared to other pixels in the array. 

TileFilterDefGaussian(<radius>, <center>) : <tile>

Given a radius and center, produce a filter definition matrix to pass to TileFilter.   Produces a blur effect using an algorithm that corrects for circular radius and using a decaying exponent in the filter shape.   The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value in averaging compared to other pixels in the array. 

TileFilterDefSharpen(<radius>, <center>) : <tile>

Given a radius and center, produce a filter definition matrix to pass to TileFilter.  Sharpens an image by convolution with a moving, square matrix to detect changes in pixel values that indicate transitions in visual appearance,  returning a tile where transitions have been enhanced with greater contrast.   The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value compared to other pixels in the array.   

TileFilterDefSquare(<radius>, <center>) : <tile>

Given the radius and center, produce a filter definition matrix to pass to TileFilter.  Produces a blur effect.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array. The <center> argument is the weight to give the center pixel: a weight of 1 means not to emphasize it.  A weight of 5 means to give the center pixel's value five times the value in averaging compared to other pixels in the array. 

TileFilterDiversity(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, calculates diversity using pixel values with non-zero weights in the filter.  Diversity is the total number of different values.  The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.

TileFilterDiversityIndex(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, calculates the  diversity index using pixel values with non-zero weights in the filter.   A diversity index provides a measure of diversity, computed as 1 - sum(individualcount^2) / (totalcount^2).  A diversity index of 0 means that all values are equal.  The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater. 

TileFilterMajor(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, determines the most frequently occurring value of pixel values with non-zero weights in the filter.  The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.    

TileFilterMax(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, determines the maximum value of pixel values with non-zero weights in the filter.  The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  

TileFilterMedian(<tile>, <radius>, <filter>) : <tile>

Given an  input tile, a radius and a tile with filter coefficients, performs a median filter.  Pixels with non-zero filter coefficients participate in computing the median, whereas pixels with zero filter coefficients and invisible pixels do not. The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.

TileFilterMin(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, determines the minimum value of pixel values with non-zero weights in the filter.  The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater. 

TileFilterStDev(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, calculates the standard deviation using pixel values with non-zero weights in the filter.   The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater. 

TileFilterStDevPop(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, calculates the square root of the population variance using pixel values with non-zero weights in the filter.   The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.

TileFilterSum(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, calculates the sum of pixel values with non-zero weights in the filter.  The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.  The function produces missing pixels if the filter shape covers no valid pixels.  GPU parallelism switches to CPU parallelism at a radius of 9 or greater.

TileFilterVar(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, calculates the sample variance using pixel values with non-zero weights in the filter.   The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  

TileFilterVarPop(<tile>, <radius>, <filter>): <tile>

Given an  input tile, a radius and a tile with filter coefficients, calculates the population variance using pixel values with non-zero weights in the filter.   The number of non-zero coefficients must be 32 or less.  The <radius> argument sets the number of pixels from the center pixel to the edge:  A radius of 1 results in a 3x3 pixel array.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.

TileFloor(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the rounded down integer value of the input tile pixel values.   See the note below on the difference between Floor and Trunc functions. 

TileFloorDecs(<tile>, <decimals>) : <tile>

Given a tile value and the desired number of decimals returns a tile with pixel values set to the integer value rounded down to the specified number of decimals of the input tile pixel values.    See the note below on the difference between Floor and Trunc functions.  

TileFlowDirAccum(<image>): <table>

Takes a 1-channel image, and returns computed flow direction and accumulation as a dual image, using a table with fields for X, Y, FlowDir, and FlowAccum. Flow direction is returned as an INT8 data type, where, 0 corresponds to 'up', and 1-2-3-4-5-6-7 proceed clockwise. Flow accumulation is returned as a FLOAT64 data type.  See illustrations and examples in the Flow Direction and Accumulation topic.

TileFlowDirAccumPar(<image>, <config>): <table>

A parallel form of the TileFlowDirAccum function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileFlowDirAccum function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileFract(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the decimal fractional part of the input tile pixel values. 

TileFractDecs(<tile>, <decimals>) : <tile>

Given a tile value and the desired number of decimals returns a tile with pixel values set to the decimal fractional part to the specified number of decimals of the input tile pixel values.  

TileGeom functions

For examples of TileGeom functions listed immediately below, see the Example: Transfer DEM Terrain Heights to Areas in a Drawing topic.

 

See also the Notes section at the end of this topic.

TileGeomAvg(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>,  and a geom in a drawing, return the average value found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomCount(<image>, <geom>): <value>

Given a single-channel image and a geom in a drawing, return the number of pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomDiversity(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the total number of different values found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomDiversityIndex(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the diversity index for the pixels that are located within the geom.  A diversity index provides a measure of diversity, computed as 1 - sum(individualcount^2) / (totalcount^2).  A diversity index of 0 means that all values are equal.  The image and the drawing must be in the same coordinate system.  

TileGeomMajor(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the most frequently occurring value found in pixels that are located within the geom.  If all values are different, the function returns the lowest value. The image and the drawing must be in the same coordinate system.

TileGeomMax(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the maximum value found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.  

TileGeomMedian(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the median value found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomMin(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the minimum value found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.  

TileGeomOverlayCount(<image>, <drawing>, <field>): <table>

 

TileGeomOverlayCountPar(<image>, <drawing>, <field>, <threads>): <table>

Given an image, a drawing, and a numeric field name in the drawing, produce an image with the same parameters as the specified image, but with each pixel in that image filled with the count of objects in the drawing that overlay that pixel.   

 

The parallel variant, TileGeomOverlayCountPar, takes an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.    If the number of threads is less than or equal to 1 the TileGeomOverlayCount function will be executed.  

TileGeomOverlayMax(<image>, <drawing>, <field>): <table>

 

TileGeomOverlayMaxPar(<image>, <drawing>, <field>, <threads>): <table>

Given an image, a drawing, and a numeric field name in the drawing, produce an image with the same parameters as the specified image, but with each pixel in that image filled with the maximum value in the specified numeric field found within all objects in the drawing that overlay that pixel.   

 

The parallel variant, TileGeomOverlayMaxPar, takes an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.    If the number of threads is less than or equal to 1 the TileGeomOverlayMax function will be executed.  

TileGeomOverlayMin(<image>, <drawing>, <field>): <table>

 

TileGeomOverlayMinPar(<image>, <drawing>, <field>, <threads>): <table>

Given an image, a drawing, and a numeric field name in the drawing, produce an image with the same parameters as the specified image, but with each pixel in that image filled with the minimum value in the specified numeric field found within all objects in the drawing that overlay that pixel.   

 

The parallel variant, TileGeomOverlayMinPar, takes an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.    If the number of threads is less than or equal to 1 the TileGeomOverlayMin function will be executed.  

TileGeomOverlaySum(<image>, <drawing>, <field>): <table>

 

TileGeomOverlaySumPar(<image>, <drawing>, <field>, <threads>): <table>

Given an image, a drawing, and a numeric field name in the drawing, produce an image with the same parameters as the specified image, but with each pixel in that image filled with the sum of values in the specified numeric field found within all objects in the drawing that overlay that pixel.  

 

The parallel variant, TileGeomOverlaySumPar, takes an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.   If the number of threads is less than or equal to 1 the TileGeomOverlaySum function will be executed.  

TileGeomStDev(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the standard deviation of values found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomStDevPop(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the square root of population variance of values found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomSample(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return one sample pixel value found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.  This function is the fastest way to capture data for a geom from an image.

TileGeomSum(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the sum of values found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomToValues(<image>, <geom>): <table>

Given a single-channel image and a geom in a drawing, returns a table with all pixels located within the geom, with X, Y, and Value fields in the table.  The image and the drawing must be in the same coordinate system.

TileGeomToValuesX2<image>, <geom>): <table>

Given a two-channel image and a geom in a drawing, returns a table with all pixels located within the geom, with X, Y, and Value (as an x2 data type)  fields in the table.  The image and the drawing must be in the same coordinate system.

TileGeomToValuesX3(<image>, <geom>): <table>

Given a three-channel image and a geom in a drawing, returns a table with all pixels located within the geom, with X, Y, and Value (as an x3 data type)  fields in the table.  The image and the drawing must be in the same coordinate system.

TileGeomToValuesX4(<image>, <geom>): <table>

Given a four-channel image and a geom in a drawing, returns a table with all pixels located within the geom, with X, Y, and Value (as an x4 data type)  fields in the table.  The image and the drawing must be in the same coordinate system.

TileGeomVar(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the sample variance of values found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileGeomVarPop(<image>, <channel>, <geom>): <value>

Given a single-channel image or a multi-channel image using the specified <channel>, and a geom in a drawing, return the population variance of values found in pixels that are located within the geom.  The image and the drawing must be in the same coordinate system.

TileHcyBgr(<tilehcy>) : <tilebgr>

Given a tile value with pixels in HCY color space returns a tile with pixel values in BGR color space.

TileHsiBgr(<tilehsi>) : <tilebgr>

Given a tile value with pixels in HSI color space returns a tile with pixel values in BGR color space.

TileHslBgr(<tilehsl>) : <tilebgr>

Given a tile value with pixels in HSL color space returns a tile with pixel values in BGR color space.

TileHsvBgr(<tilehsv>) : <tilebgr>

Given a tile value with pixels in HSV color space returns a tile with pixel values in BGR color space.

TileHypot(<x>, <y>) : <tile>

The great and ancient Pythagorean theorem: The square root of the sum of the squares of the two sides of a right triangle.   Given two tile values or a tile value and a number, returns a tile with pixel values set to  the hypotenuse taking two input values  as DX and DY.

TileInterpolate(<interpolation>, <valuex4>) : <tile>

Takes a <valuex4> rectangle and an <interpolation> object created by one of the TileInterpolateKriging or TileInterpolateTriangulation functions, and creates a tile with interpolated pixel values.

TileInterpolateGravity(<drawing>, <radius>, <neighbors>) : <interpolation>

Takes a drawing and interpolation parameters and uses gravity formulae to return an interpolation object that can be used to produce tiles.

 

Heights are taken from Z values in the drawing geoms. Geoms without Z values are ignored. All geoms are converted to coordinates. Duplicate XY coordinates are ignored: if duplicate XY coordinates have different Z values, the function uses one of these values and ignores any other Z values.

 

Interpolation parameters:

 

  • <radius> - Radius for neighbor searches (Kriging interpolates heights from closest coordinates),

  • <neighbors> - Number of neighbors to use.

 

Interpreting various combinations of specified (positive value) or auto-computed (zero or negative value) for <radius> and <neighbors>:

 

  • Specified Radius and Neighbors auto-computed = Use all neighbors within the specified radius.

  • Both Radius and Neighbors auto-computed = Use all Voronoi neighbors.  

  • Specified number of Neighbors, but Radius auto-computed = Radius set by the system according to the global interpolation picture.

  • Specified number of Neighbors, and specified Radius = Use up to the specified number of neighbors within the specified radius.

 

See the SQL Example: Kriging topic.

TileInterpolateKriging(<drawing>, <radius>, <neighbors>, <model>) : <interpolation>

Takes a drawing and interpolation parameters and uses Kriging to return an interpolation object that can be used to produce tiles.

 

Heights are taken from Z values in the drawing geoms. Geoms without Z values are ignored. All geoms are converted to coordinates. Duplicate XY coordinates are ignored: if duplicate XY coordinates have different Z values, the function uses one of these values and ignores any other Z values.     If there is too little data to set up the model, Kriging degrades to Gravity interpolation.

 

Interpolation parameters:

 

  • <radius> - Radius for neighbor searches (Kriging interpolates heights from closest coordinates),

  • <neighbors> - Number of neighbors to use

  • <model> - Interpolation model.

 

Interpolation model codes:

 

  • zero or negative value = autoselect the model

  • 1 = linear model

  • 2 = circular model

  • 3 = exponential model

  • 4 = Gaussian model

  • 5 = power model

  • 6 = rational model

  • 7 = spherical model

 

Interpreting various combinations of specified (positive value) or auto-computed (zero or negative value) for <radius> and <neighbors>:

 

  • Specified Radius and Neighbors auto-computed = Use all neighbors within the specified radius.

  • Both Radius and Neighbors auto-computed = Use all Voronoi neighbors.  

  • Specified number of Neighbors, but Radius auto-computed = Radius set by the system according to the global interpolation picture.

  • Specified number of Neighbors, and specified Radius = Use up to the specified number of neighbors within the specified radius.

 

See the SQL Example: Kriging topic.

TileInterpolateKrigingPar(<drawing>, <radius>, <neighbors>, <model>, <config>) : <interpolation>

A parallel variant of TileInterpolateKriging, taking an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.  See the SQL Example: Kriging topic.

TileInterpolateKrigingMedianPolish(<drawing>, <radius>,  <step>, <neighbors>, <model>) : <interpolation>

Takes the same parameters as TileInterpolateKriging and returns an interpolation object that can be used to produce tiles using Kriging with median-polish, that is, additional processing intended to improve interpolation quality.  The <step> argument sets the size of the step for each application of median polish algorithm.   0 or negative step  = use automatic step value.  See the SQL Example: Kriging topic.

TileInterpolateKrigingMedianPolishPar(<drawing>, <radius>,  <step>, <neighbors>, <model>, <config>) : <interpolation>

A parallel variant of TileInterpolateKrigingMedianPolish, taking an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.  The <step> argument sets the size of the step for each application of median polish algorithm.   0 or negative step  = use automatic step value.  See the SQL Example: Kriging topic.

TileInterpolateKrigingRegression(<drawing>, <radius>, <neighbors>, <model>,<regression>) : <interpolation>

Takes a drawing and interpolation parameters and uses Kriging to return an interpolation object that can be used to produce tiles.

 

Heights are taken from Z values in the drawing geoms. Geoms without Z values are ignored. All geoms are converted to coordinates. Duplicate XY coordinates are ignored: if duplicate XY coordinates have different Z values, the function uses one of these values and ignores any other Z values.     If there is too little data to set up the model, Kriging degrades to Gravity interpolation.

 

Interpolation parameters:

 

  • <radius> - Radius for neighbor searches (Kriging interpolates heights from closest coordinates),

  • <neighbors> - Number of neighbors to use

  • <model> - Interpolation model.

 

Interpolation model codes:

 

  • zero or negative value = autoselect the model

  • 1 = linear model

  • 2 = circular model

  • 3 = exponential model

  • 4 = Gaussian model

  • 5 = power model

  • 6 = rational model

  • 7 = spherical model

 

Regression model codes:

 

  • zero or negative value = autoselect the model

  • 1 = linear model

  • 2 = quadratic model

 

Interpreting various combinations of specified (positive value) or auto-computed (zero or negative value) for <radius> and <neighbors>:

 

  • Specified Radius and Neighbors auto-computed = Use all neighbors within the specified radius.

  • Both Radius and Neighbors auto-computed = Use all Voronoi neighbors.  

  • Specified number of Neighbors, but Radius auto-computed = Radius set by the system according to the global interpolation picture.

  • Specified number of Neighbors, and specified Radius = Use up to the specified number of neighbors within the specified radius.

 

About regression Kriging: Imagine an undulating surface that lies on the slope of a large hill, where if the surface were not bumpy we would have a smooth plane inclined at the overall angle of the hill.  Suppose now we have many points that lie on the surface with each point providing the X,Y, and Z value of the surface at that point. Some regions of the surface have relatively few points or are lacking points.  

 

The general task of Kriging is to take the collection of many points and to re-create the surface, filling in through computation some plausible interpolation in regions where sample points are sparse or missing.  Ordinary Kriging simply takes the X,Y,Z values of the points and applies Kriging computations to interpolate a surface.

 

Regression Kriging first attempts to ascertain the overall inclined plane and to remove that as a bias, to allow considering the undulating surface as if it were arranged horizontally and not tilted on the overall slope of a hill.  A Kriging calculation is performed on the adjusted, "as if level,"  coordinates of the points, and then the resulting interpolated surface is titled back to the original overall incline.  The choice of linear or quadratic regression is a choice of how the original "overall" tilted-plane setting is determined.

 

Regression Kriging can identify and set aside more complex biases than the case of an undulating surface within a simple, overall incline in a hill.  This non-mathematical description provides an analogy, not an exact phrasing of the math involved, to help non-mathematicians understand how Regression Kriging can provide better results than ordinary Kriging.

TileInterpolateKrigingRegressionPar(<drawing>, <radius>, <neighbors>, <model>, <regression>, <config>) : <interpolation>

A parallel variant of TileInterpolateKrigingRegression, taking an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.  

TileInterpolateTriangulation(<drawing>) : <interpolation>

Takes a drawing and returns an interpolation object that can be used to produce tiles using triangulation. As with Kriging, all geoms are currently converted to coordinates. This will be changed to use constrained triangulation for lines and either convert areas to boundaries or ignore them.  

TileInterpolateTriangulationPar(<drawing>, <config>) : <interpolation>

A parallel variant of TileInterpolateTriangulation, taking an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.  

TileInterpolateTriangulationSeg(<drawing>, <dest>) : <interpolation>

Takes a drawing and returns an interpolation object that can be used to produce tiles using constrained triangulation.  The constrained triangulation keeps segments from lines and areas, which are converted to boundary lines. The <dest> boolean parameter provides an option to improve triangulation of contours using DEST (true = use DEST).  The DEST (Determination of Earth Surface Structures) algorithm helps to remove or reduce terracing effects when contouring from contour lines or other regular data.

TileInterpolateTriangulationSegPar(<drawing>, <dest>, <config>) : <interpolation>

A parallel variant of TileInterpolateTriangulationSeg, taking an additional parameter with the thread configuration.   Use ThreadConfig to generate a JSON string with the desired number of threads.  

TileJ0(<tile>) : <tile>

A Bessel function of the first kind: Given a tile value returns a tile with pixel values set to the result of the Bessel function J0(x) using the input tile pixel values.  

TileJ1(<tile>) : <tile>

A Bessel function of the first kind: Given a tile value returns a tile with pixel values set to the result of the Bessel function J1(x) using the input tile pixel values.  

TileJn(<order>, <tile>) : <tile>

The nth Bessel function of the first kind: Given an order and a tile value returns a tile with pixel values set to the result of the Bessel function Jn(x) for order n using the input tile pixel values.  

TileJson(<tile>): <json>

Takes a tile and prints it into a JSON text string: [ p1, p2, p3, ... ]. Pixels are ordered by Y and then by X, with row 0 being first. There are no extra separators between rows. If there are multiple channels, each pixel is printed as the value of channel 0, then the value of channel 1, etc., as in [ ... c0, c1, c2, ... ]. Invisible pixels are printed as 'null' (an allowed keyword in JSON). If there are multiple channels, invisible pixels are printed as a sequence of 'null' values for each channel.

TileLgamma(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the log-gamma function, taking the natural logarithm of the gamma function, for the input tile pixel values.

TileLog(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the base e logarithm (also called the natural logarithm) of the input tile pixel values.

TileLog10(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the base 10 logarithm (also called the common logarithm) of the input tile pixel values.

TileLog1p(<tile>) : <tile>

Given a tile value with pixel values x, returns a tile with pixel values set to Log(x+1) where Log is the base e logarithm (also called the natural logarithm) of the value.

TileLog2(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the base 2 logarithm (also called the binary logarithm) of the input tile pixel values.

TileMake(<cx>, <cy>, <value>) : <tile>

Given cx and xy extents and a value (a number, an xN vector or a boolean) returns a new tile. If the requested tile size is too large, the function returns NULL.

TileMaskExtract(<tile>) : <mask>

Do not use: This is a service function subject to change that is exposed in the query builder as a placeholder for infrastructure in progress for future updates. Takes an arbitrary tile and creates a tile of boolean values, with true for visible pixels, false for invisible pixels.

TileMaskReplace(<tile>, <mask>) : <tile>

Do not use: This is a service function subject to change that is exposed in the query builder as a placeholder for infrastructure in progress for future updates. Takes an arbitrary tile and a tile of boolean values, and makes the pixels in the first tile visible or invisible according to the booleans. Whenever an invisible pixel is turned into visible, it gets a value of zero.

TileMax(<p>, <q>) : <tile>

Takes a tile and a value and returns the greater (maximum) value of the two for each pixel position.  

 

For example,  TileMax([Tile], -10) compares the value in the tile for each pixel to -10 and chooses which is the greater.  Used in a Transform pane Expression that would have the effect of setting all pixel values less than -10 to -10.  

 

For example, if a tile consists of a single channel with values from 0 to 255 in each pixel, then TileMax([Tile], 150) will return a tile where each pixel has the value of the corresponding pixel in [Tile] except that if that value is less than 150 then the pixel will have a value of 150.

 

The value could be another tile, so that TileMax([Tile1], [Tile2]) for each pixel returns whichever is the greater value of Tile1 or Tile2.

TileMin(<p>, <q>) : <tile>

Takes a tile and a value and returns the lesser (minimum) value of the two for each pixel position.  

 

For example,  TileMin([Tile], -10) compares the value in the tile for each pixel to -10 and chooses which is the lesser.  Used in a Transform pane Expression that would have the effect of setting all pixel values greater than -10 to -10.  

 

For example, if a tile consists of a single channel with values from 0 to 255 in each pixel, then TileMin([Tile], 150) will return a tile where each pixel has the value of the corresponding pixel in [Tile] except that if that value is more than 150 then the pixel will have a value of 150.

 

The value could be another tile, so that TileMin([Tile1], [Tile2]) for each pixel returns whichever is the lesser value of Tile1 or Tile2.

TileNoise(<tile>, <range>) : <tile>

Given a tile value and a range number, returns a tile with pixel values containing random noise values over the given range.

TilePow(<base>, <power>) : <tile>

Given a tile value returns a tile with pixel values set to the base (could be a tile or a numeric value) raised to the specified power value.   For example,  A power of 2 is the base value squared while a power of 3 is the base value cubed.  

TileRcbrt(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to reciprocal cube root of the input tile pixel values.   The reciprocal cube root is also known as the inverse cube root:  1 divided by the cube root of the input.

TileRemoveBorder(<tile>, <border>): <tile>

Removes a border region of pixels of the given size from a tile. If the border size is too big for the passed tile, returns NULL. If the border size is negative or zero, returns an unmodified tile.   GPU parallelism switches to CPU parallelism at a border size of 9 pixels or more.  Calls to tile functions which use borders of 9 or more pixels automatically dispatch to CPU parallelism, and can freely intermix with calls dispatched to GPU parallelism.

TileRound(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the fractional part rounded up or down to the nearest integer of the input tile pixel values.

TileRoundDecs(<tile>, <decimals>) : <tile>

Given a tile value returns a tile with pixel values set to the fractional part, rounded up or down to the number of decimals specified, of the input tile pixel values.

TileRsqrt(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to reciprocal square root of the input tile pixel values.   The reciprocal cube root is also known as the inverse square root:  1 divided by the square root of the input.

TileSign(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to 1 or -1 when the input tile pixel values are positive or negative, respectively.

TileSin(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the sine of the input tile pixel values.

TileSinh(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the hyperbolic sine of the input tile pixel values.

TileSlope(<tile>, <radius>, <scalex3>) : <tile>

Given a tile value, a radius, and XYZ scales, returns a tile with pixel values set to the slope in degrees of the surface implied by treating input tile pixel values as heights.   GPU parallelism switches to CPU parallelism at a radius of 9 or greater.  

TileSqrt(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the square root of the input tile pixel values.

TileTan(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the tangent of the input tile pixel values.

TileTanh(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the hyperbolic tangent of the input tile pixel values.

TileTgamma(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the gamma function of the input tile pixel values.

TileToValues(<tile>) : <table>

Given a tile returns a table where each row is a pixel with fields x, y, and value. The returned value field is used for numbers or booleans.  Using TileToValues together with aggregates provides a more general way of getting average, count, max, min and sums for tiles than providing a specific function for each such operation.

TileToValuesX2(<tile>) : <table>

A variation of TileToValues for tiles containing x2 vector values.   Given tile returns a table where each row is a pixel with fields x, y, value, the value field being a float64x2 vector.

TileToValuesX3(<tile>) : <table>

A variation of TileToValues for tiles containing x3 vector values.   Given tile returns a table where each row is a pixel with fields x, y, value, the value field being a float64x3 vector.

TileToValuesX4(<tile>) : <table>

A variation of TileToValues for tiles containing x4 vector values.   Given tile returns a table where each row is a pixel with fields x, y, value, the value field being a float64x4 vector.

TileTraceArea(<image>, <value>, <quant>): <geom>

Takes an image, a value to trace and a quantization factor, and returns a single area covering pixels with the specified value.

 

If the image contains more than one channel, the trace value must be an xN value of the appropriate size. The quantization factor remains a single numeric value that is applied to all channels simultaneously.

 

The quantization factor is used to extend the area to pixels with values close to the traced value. If the quantization factor is negative or zero, any differences in pixel values are considered significant and the returned area covers pixels with values exactly coinciding with the traced value.

 

If the quantization factor is positive, pixel values are quantized using the following formula:

 

pixelNew = floor(pixel / quant) * quant

 

Pixels that quantize to the same value are considered to be the same and the returned area covers them all.

 

For example, using a quant size of 100, pixel values between 0 and 99.9... are considered to be the same, pixel values between 100 and 199.9... are considered to be the same,  and so on.

 

See the Example: Trace Vector Areas from Raster Pixels topic for a transform template based example.

TileTraceAreaPar(<image>, <value>, <quant>, <config>): <geom>

A parallel form of the TileTraceArea function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileTraceArea function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileTraceAreas(<image>, <quant>, <decompose>) : <table>

Similar to TileTraceArea but creates multiple areas from a 1-channel image.   Takes a 1-channel image and a quantization factor, and returns a table of areas covering pixels with different values with fields for Geom and Value, with Value being a FLOAT64.    The decompose argument is true or false: when true, the result is decomposed into multiple objects when a single object would exceed 64 million coordinates.

TileTraceAreasPar(<image>, <quant>, <decompose>, <config>) : <table>

A parallel form of the TileTraceAreas function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileTraceAreas function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileTraceAreasX2(<image>, <quant>, <decompose>) : <table>

Similar to TileTraceArea but creates multiple areas from a 2-channel image.   Takes a 2-channel image and a quantization factor, and returns a table of areas covering pixels with different values with fields for Geom and Value, with Value being a FLOAT64x2.      The decompose argument is true or false: when true, the result is decomposed into multiple objects when a single object would exceed 64 million coordinates.

TileTraceAreasX2Par(<image>, <quant>, <decompose>, <config>) : <table>

A parallel form of the TileTraceAreasX2 function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileTraceAreasX2 function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileTraceAreasX3(<image>, <quant>, <decompose>) : <table>

Similar to TileTraceArea but creates multiple areas from a 3-channel image.   Takes a 3-channel image and a quantization factor, and returns a table of areas covering pixels with different values with fields for Geom and Value, with Value being a FLOAT64x3.      The decompose argument is true or false: when true, the result is decomposed into multiple objects when a single object would exceed 64 million coordinates.

TileTraceAreasX3Par(<image>, <quant>, <decompose>, <config>) : <table>

A parallel form of the TileTraceAreasX3 function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileTraceAreasX3 function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileTraceAreasX4(<image>, <quant>, <decompose>) : <table>

Similar to TileTraceArea but creates multiple areas from a 4-channel image.   Takes a 4-channel image and a quantization factor, and returns a table of areas covering pixels with different values with fields for Geom and Value, with Value being a FLOAT64x4.      The decompose argument is true or false: when true, the result is decomposed into multiple objects when a single object would exceed 64 million coordinates.

TileTraceAreasX4Par(<image>, <quant>, <decompose>, <config>) : <table>

A parallel form of the TileTraceAreasX4 function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileTraceAreasX4 function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileTrunc(<tile>) : <tile>

Given a tile value returns a tile with pixel values set to the truncated integer value of the input tile pixel values.     See the note below on the difference between Floor and Trunc functions.

TileTruncDecs(<tile>, <decimals>) : <tile>

Given a tile value and a number of decimal positions returns a tile with pixel values set to the truncated value, to the specified number of decimals, of the input tile pixel values.    See the note below on the difference between Floor and Trunc functions.

TileUpdatePyramids(<image>) : <table>

Updates intermediate levels for an image.  The image must use an rtree index on x-y-tile fields.   Given an image the function updates intermediate levels and returns the number of update tiles.

TileValueAvg(<tile>): <value>

Return the average value of all pixels in the tile.

TileValueCount(<tile>): <value>

Return the count of non-NULL values in the tile.

TileValueMax(<tile>): <value>

Return the maximum pixel value in the tile.

TileValueMin(<tile>): <value>

Return the minimum pixel value in the tile.

TileValueStDev(<tile>): <value>

Return the standard deviation of pixel values in the tile.

TileValueStDevPop(<tile>): <value>

Return the square root of the population variance for pixel values in the tile.

TileValueSum(<tile>): <value>

Return the sum of pixel values in the tile.

TileValueVar(<tile>): <value>

Return the sample variance of pixel values in the tile.

TileValueVarPop(<tile>): <value>

Return the population variance of pixel values in the tile.

TileViewshedAreaAll(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>): <geom>

 

Takes a viewshed buffer, a drawing with XYZ points, viewshed creation parameters, and returns an area visible from all points in the drawing.

 

Viewshed creation parameters are: an option of whether Z values for points in the drawing are relative to heights in the image (true) or are absolute heights (false), the maximum visible radius (a negative value or zero means there is no limit), and minimum and maximum angles of the camera in degrees (-90 / 90 means that there are no limits).

TileViewshedAreaAllPar(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>, <config>): <geom>

A parallel form of the TileViewshedAreaAll function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileViewshedAreaAll function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileViewshedAreaAny(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>): <geom>

 

Takes the same parameters as TileViewshedAreaAll and returns an area visible from any point in the drawing.

TileViewshedAreaAnyPar(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>, <config>): <geom>

A parallel form of the TileViewshedAreaAny function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileViewshedAreaAny function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileViewshedMake(<image>, <refraction>, <useDatumCurvature>): <viewsheds>

Takes an image and global viewshed creation parameters, and returns a viewshed buffer. Global viewshed creation parameters are: a refraction coefficient (0 allowed), and an option to use datum curvature.

TileViewshedMakePar(<image>, <refraction>, <useDatumCurvature>, <config>): <viewsheds>

A parallel form of the TileViewshedMake function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileViewshedMake function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileViewshedTilesCount(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>): <table>

Takes a viewshed buffer, a drawing with XYZ points, viewshed creation parameters, and returns a table with tiles with pixel values containing the number of points visible from the pixel.

 

Viewshed creation parameters are: an option of whether Z values for points in the drawing are relative to heights in the image (true) or are absolute heights (false), the maximum visible radius (a negative value or zero means there is no limit), and minimum and maximum angles of the camera in degrees (-90 / 90 means that there are no limits).

TileViewshedTilesCountPar(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>, <config>): <table>

A parallel form of the TileViewshedTilesCount function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileViewshedTilesCount function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileViewshedTilesLevelAll(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>): <table>

Takes a viewshed buffer, a drawing with XYZ points, viewshed creation parameters, and returns a table with tiles with pixel values containing the visibility level of the pixel from all points.

 

If the visibility level of the pixel is positive or zero, the pixel is visible from all points. If the visibility level of the pixel is negative, it contains the difference between the height at which all points become visible and the height of the pixel.  The bigger the magnitude of the value, the more the pixel has to be raised to become visible from all points.

 

Viewshed creation parameters are: an option of whether Z values for points in the drawing are relative to heights in the image (true) or are absolute heights (false), the maximum visible radius (a negative value or zero means there is no limit), and minimum and maximum angles of the camera in degrees (-90 / 90 means that there are no limits).

TileViewshedTilesLevelAllPar(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>, <config>): <table>

A parallel form of the TileViewshedTilesLevelAll function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileViewshedTilesLevelAll function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileViewshedTilesLevelAny(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>, <angleMax>): <table>

Takes the same parameters as TileViewshedTilesLevelAll and returns a table with tiles with pixel values containing the visibility level of the pixel from any point.  

 

If the visibility level of the pixel is positive or zero, the pixel is visible from any point. If the visibility level of the pixel is negative, it contains the difference between the height at which any point becomes visible and the height of the pixel.  The bigger the magnitude of the value, the more the pixel has to be raised to become visible from any point.

TileViewshedTilesLevelAnyPar(<viewsheds>, <drawing>, <relativeZ>, <radiusMax>, <angleMin>,<angleMax>, <config>): <table>

A parallel form of the TileViewshedTilesLevelAny function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileViewshedTilesLevelAny function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileViewshedTraceLine(<viewsheds>, <beg>, <end>, <relativeZ>, <angleMin>, <angleMax>): <level>

Takes a viewshed buffer, begin and end XYZ coordinates, and viewshed creation parameters, and returns the visibility level of the end coordinate from the begin coordinate.

 

If the visibility level is positive or zero, the end coordinate is visible from the begin coordinate. If the visibility level is negative, it contains the difference between the height at which the end coordinate becomes visible and the height of the coordinate.  The bigger the magnitude of the value, the more the end coordinate has to be raised to become visible from the begin coordinate.

 

Viewshed creation parameters are: an option of whether Z values for points in the drawing are relative to heights in the image (true) or are absolute heights (false), the maximum visible radius (a negative value or zero means there is no limit), and minimum and maximum angles of the camera in degrees (-90 / 90 means that there are no limits).

TileWatershedAreas(<watersheds>, <flowMin>): <table>

Takes a watershed object and a number for minimum flow, and returns a table of watershed areas with fields for: Geom, Stream, Target, OrderShreve, OrderStrahler, Value and ValueSum.  See illustrations and examples in the Watersheds topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedAreasPar(<watersheds>, <flowMin>, <config>): <table>

A parallel form of the TileWatershedAreas function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedAreas function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedAreasSinks(<watersheds>, <keepEscaping>): <table>

Takes a watershed object and a Boolean flag,, and returns a table of watershed areas for all sinks with a Value field giving the flow in each sink.   The <keepEscaping> Boolean flag specifies whether to keep (true) or discard (false) areas that flow out of the image.  See illustrations and examples in the Watersheds topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedAreasSinksPar(<watersheds>, <keepEscaping>, <config>): <table>

A parallel form of the TileWatershedAreasSinks function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedAreasSinks function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedAreaUpstream(<watersheds>, <coordx2>): <geom>

Takes a watershed object and a float64x2 coordinate, and returns the upstream watershed area for the coordinate with a Value field giving the flow in the area.  See illustrations and examples in the Watersheds topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedAreaUpstreamPar(<watersheds>, <coordx2>, <config>): <geom>

A parallel form of the TileWatershedAreaUpstream function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedAreaUpstream function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedAreasUpstream(<watersheds>, <drawing>, <keepOverlaps>): <table>

Takes a watershed object and a drawing for points, and returns a table of upstream watershed areas for each point with a Value field giving the flow in each area, and a Coord field giving the float64x2 coordinates of each source point. The <keepOverlaps> Boolean keeps overlaps if true and eliminates overlaps if false.  See illustrations and examples in the Upstream Areas and Lines topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedAreasUpstreamPar(<watersheds>, <drawing>, <keepOverlaps>, <config>): <table>

A parallel form of the TileWatershedAreasUpstream function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedAreasUpstream function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedLines(<watersheds>, <flowMin>): <table>

Takes a watershed object and a number for minimum flow, and returns a table of watershed stream lines with fields for: Geom, Stream, Target, OrderShreve, OrderStrahler, Value and ValueSum.  See illustrations and examples in the Watersheds topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedLinesPar(<watersheds>, <flowMin>, <config>): <table>

A parallel form of the TileWatershedLines function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedLines function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedLineDownstream(<watersheds>, <coordx2>): <geom>

Takes a watershed object, a float64x2 coordinate, and a number for minimum flow, and returns the downstream watershed line for the coordinate. See illustrations and examples in the Watersheds topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedLineDownstreamPar(<watersheds>, <coordx2>, <config>): <geom>

A parallel form of the TileWatershedLineDownstream function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedLineDownstream function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedLinesDownstream(<watersheds>, <drawing>, <keepOverlaps>): <table>

Takes a watershed object, a drawing for points, and returns a table of downstream watershed lines for each point with a Coord field giving the float64x2 coordinates of each source point.  The <keepOverlaps> Boolean keeps overlaps if true and eliminates overlaps if false.   See illustrations and examples in the Downstream Lines topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedLinesDownstreamPar(<watersheds>, <drawing>, <keepOverlaps>, <config>): <table>

A parallel form of the TileWatershedLinesDownstream function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedLinesDownstream function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedLineUpstream(<watersheds>, <coordx2>, <flowMin>): <geom>

Takes a watershed object, a float64x2 coordinate, and a number for minimum flow, and returns the upstream watershed line for the coordinate.  See illustrations and examples in the Upstream Areas and Lines topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedLineUpstreamPar(<watersheds>, <coordx2>, <flowMin>, <config>): <geom>

A parallel form of the TileWatershedLineUpstream function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedLineUpstream function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedLinesUpstream(<watersheds>, <drawing>, <flowMin>, <keepOverlaps>): <table>

Takes a watershed object, a drawing for points, and a number for minimum flow, and returns a table of upstream watershed lines for each point with a Value field giving the flow, and a Coord field giving the float64x2 coordinates of each source point.  The <keepOverlaps> Boolean keeps overlaps if true and eliminates overlaps if false.    See illustrations and examples in the Watersheds topic.  Create a watershed object using  TileWatershedMakePar or TileWatershedMakeDirPar.

TileWatershedLinesUpstreamPar(<watersheds>, <drawing>, <flowMin>, <keepOverlaps>,<config>): <table>

A parallel form of the TileWatershedLinesUpstream function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedLinesUpstream function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedMake(<image>, <useWeights>): <watersheds>

Takes an image containing heights and a boolean flag to use or not use weights, and returns a watershed object  (a TABLE).   The watershed object can be passed to various TileWatershedxxx functions to create desired geometries.

 

To use weights, pass a two-channel image, with heights in the first channel and weights in the second channel, and pass TRUE for the <useWeights> parameter.  Weights indicate the amount of precipitation on that pixel.  For example, a weight of 2 in a pixel would indicate twice the precipitation of  weight of 1 in a pixel.

 

We often want to compute various geometries on the same watershed, such as watershed areas, watershed lines, upstream watershed areas, etc.  But watersheds are costly to compute:  if we want three different geometries it is wasteful to compute the watershed three times, once within each function.   Using TileWatershedMake we can compute the watersheds object just once and then reuse that same watersheds object three times for quick computations of geometry desired.

 

Watersheds can be computed either from images that have a height in each pixel, or from images that have a direction in each pixel.   Instead of having two different forms of each geometry function (one using heights and one using directions), we can have just one form of each geometry function that takes a watershed object.   

 

We can then compartmentalize the creation of watershed objects into two different Make functions, one which creates watershed objects from heights, TileWatershedMake, and the other which creates watershed objects from directions, TileWatershedMakeDir.

 

This greatly reduces the number of different functions, while retaining the flexibility of creating whatever geometry is desired from watersheds that are created either from heights or from directions.

 

For an example of use, see the Upstream Areas and Lines topic.

TileWatershedMakePar(<image>, <useWeights>, <config>): <watersheds>

A parallel form of the TileWatershedMake function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedMake function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileWatershedMakeDir(<imageDir>, <useWeights>): <watersheds>

Takes an image containing directions and a boolean flag to use or not use weights, and returns a watershed object (a TABLE).    The watershed object can be passed to various TileWatershedxxx functions to create desired geometries.

 

Directions are one of eight integer numbers from 0 to 7 as given in the Flow Direction and Accumulation  topic.

 

To use weights, pass a two-channel image, with directions in the first channel and weights in the second channel, and pass TRUE for the <useWeights> parameter.  Weights indicate the amount of precipitation on that pixel.  For example, a weight of 2 in a pixel would indicate twice the precipitation of  weight of 1 in a pixel.

 

We often want to compute various geometries on the same watershed, such as watershed areas, watershed lines, upstream watershed areas, etc.  But watersheds are costly to compute:  if we want three different geometries it is wasteful to compute the watershed three times, once within each function.   Using TileWatershedMakeDir we can compute the watersheds object just once and then reuse that same watersheds object three times for quick computations of geometry desired.

 

Watersheds can be computed either from images that have a height in each pixel, or from images that have a direction in each pixel.   Instead of having two different forms of each geometry function (one using heights and one using directions), we can have just one form of each geometry function that takes a watershed object.   

 

We can then compartmentalize the creation of watershed objects into two different Make functions, one which creates watershed objects from heights, TileWatershedMake, and the other which creates watershed objects from directions, TileWatershedMakeDir.

 

This greatly reduces the number of different functions, while retaining the flexibility of creating whatever geometry is desired from watersheds that are created either from heights or from directions.

 

For an example using a Make function, see the Upstream Areas and Lines topic.

TileWatershedMakeDirPar(<imageDir>, <useWeights>, <config>): <watersheds>

A parallel form of the TileWatershedMakeDir function that takes a parameter for the suggested number of threads as encoded in the JSON <config> string as "threads".  If the number of threads is less than or equal to 1 the TileWatershedMakeDir function will be executed.  Use ThreadConfig to generate a JSON string with the desired number of threads.

TileY0(<tile>) : <tile>

A Bessel function of the second kind: Given a tile value returns a tile with pixel values set to the result of the Bessel Function Y0(x) using the input tile pixel values.  

TileY1(<tile>) : <tile>

A Bessel function of the second kind: Given a tile value returns a tile with pixel values set to the result of the Bessel Function Y1(x) using the input tile pixel values.  

TileYn(<order>, <tile>) : <tile>

The nth Bessel function of the second kind: Given an order and a tile value returns a tile with pixel values set to the result of the Bessel Function Yn(x) for order n using the input tile pixel values.  

Trunc(<value>) : <value>

Given a value returns the truncated integer value of the input.

 

? Trunc(3.1415926536)

 

Returns 3.

 

See the note below on the difference between Floor and Trunc functions.

TruncDecs(<value>, <decimals>) : <value>

Given value and a number of decimal positions returns the truncated value, to the specified number of decimals, of the input.

 

? TruncDecs(3.1415926536, 4)

 

Returns 3.1415.

 

See the note below on the difference between Floor and Trunc functions.

TypeName(<value>) : <name>

Given a value, returns a string giving the data type of the value.

 

? TypeName(3.1415926)

 

Returns:

 

nvarchar: float64

 

UuidMakeNew() : <uuid>

Returns a UUID value

 

? UuidMakeNew()

 

Returns (always different):

 

uuid: 3681de5a-a39c-4261-aa8a-ccd98e8a15ea

 

ValueCount(<table>) : <number>

Given a table returns the number of records in the table.

ValueSequence(<begin>, <end>, <step>) : <table>

Given a beginning value, an ending value, and steps between values returns a table where each row is a value from beginning to end with the specified step between.

 

? CALL ValueSequence(0, 10, 2)

 

Returns a table:

ValueSequenceRandom(<count>, <seed>) : <table>

Given the number of values to generate and a seed value, return a table of floating-point random values between 0 and 1.   If the seed value is zero or negative, it is ignored and the random generator uses a seed value unique for the session.

 

? CALL ValueSequenceRandom(6, 3.1415)

 

Returns a table:

The random number generator used is xorshift128+.

ValueSequenceRandomInt(<count>, <limit>, <seed>) : <table>

Given the number of values to generate, an integer limit and a seed value, return a table of integer random values between 0 and (limit - 1). If the seed value is zero or negative, it is ignored and the random generator uses a seed value unique for the session.

 

? CALL ValueSequenceRandomInt(6, 100, 0)

 

Returns a table:

The random number generator used is xorshift128+.

ValueSequenceTileXY(<valuex4>, <tilesizex2>, <contained>) : <table>

Takes a rect value for the image, a tile size value, and a contained / touching boolean switch, and returns a table of XY indexes for tiles either completely within or with any part within the specified rect. The returned table includes the following fields:

 

  • X - The X coordinate of a tile. Can be negative.
  • Y - The Y coordinate of a tile. Can be negative.
  • Rect - The rect of a tile.

 

The Rect value could be computed by the user from the X and Y values and the tile size, but is provided regardless for convenience.

VectorBgrHcy(<bgr>) : <hcy>

Convert BGR to HCY:  Given a vector value in BGR color space returns a vector value in HCY color space.

VectorBgrHsi(<bgr>) : <hsi>

Convert BGR to HSI:  Given a vector value in BGR color space returns a vector value in HSI color space.

VectorBgrHsl(<bgr>) : <hsl>

Convert BGR to HSL:  Given a vector value in BGR color space returns a vector value in HSL color space.

VectorBgrHsv(<bgr>) : <hsv>

Convert BGR to HSV:  Given a vector value in BGR color space returns a vector value in HSV color space.

VectorHcyBgr(<hcy>) : <bgr>

Convert HCY to BGR:  Given a vector value in HCY color space returns a vector value in BGR color space.

VectorHsiBgr(<hsi>) : <bgr>

Convert HSI to BGR:  Given a vector value in HSI color space returns a vector value in BGR color space.

VectorHslBgr(<hsl>) : <bgr>

Convert HSL to BGR:  Given a vector value in HSL color space returns a vector value in BGR color space.

VectorHsvBgr(<hsv>) : <bgr>

Convert HSV to BGR:  Given a vector value in HSV color space returns a vector value in BGR color space.

VectorMakeX2(<value>, <value>) : <valuex2>

Given two numeric values return an x2 vector containing those values as component parts.

VectorMakeX3(<value>, <value>, <value>) : <valuex3>

Given three numeric values return an x3 vector containing those values as component parts.

VectorMakeX4(<value>, <value>, <value>, <value>) : <valuex4>

Given four numeric values return an x4 vector containing those values as component parts.

VectorValue(<valuexN>, <index>) : <value>

Given a vector value and an index (zero based counting) returns the value at that index position in the vector.   For example, if a vector in a field called Color is uint8x3 it is a vector with three uint8 values.   VectorValue([Color], 0)  returns the value of the first of the three uint8 values in the vector and VectorValue([Color], 2) returns the third uint8 value in the vector.

VectorValues(<valuexN>, <valuexN>) : <valuexN>

Rearranges component values of a vector.   Given a vector of values and a vector of indexes, returns a vector of values recomposed according to indexes. Both input vectors have to be of the same size. If the index vector contains a value that is not a valid index, the relevant part of the vector is replaced with 0.

 

Example:

 

VectorValues(VectorMakeX2(X, Y), VectorMakeX2(1, 0))

 

Returns an x2 vector with X and Y values from the original vector swapped.   

 

To explain why that is so:  If the original vector is a two value vector represented by the set {X,Y} and the index is a two value vector represented by the set {1,0}, the index tells the function to return as the first position in the result vector whatever is in the second position of the original vector (to mean "second" in zero-based counting we use the number 1) and to run as the second position in the result vector whatever is in the first position of the original vector (to mean "first" in zero-based counting we use the number 0).  Looking at the original set of {X,Y}, Y is in the second position and X is in the first position.   So if we do as the index set of {1,0} instructs, we will create a result set of {Y,X}.

 

Example:

 

VectorValues(VectorMakeX3(B, G, R), VectorMakeX3(2, 1, 0))

 

Creates an X3 vector result where the component values are in the order R, G and B, that is, the third, second and first parts of the original vector.

Y0(<value>) : <value>

A Bessel function of the second kind: Given a value x returns the result of the Bessel Function Y0(x).  

Y1(<value>) : <value>

A Bessel function of the second kind: Given a value x returns the result of the Bessel Function Y1(x).  

Yn(<order>, <value>) : <value>

The nth Bessel function of the second kind: Given an order n and a value x returns the result of the Bessel Function Yn(x).  

 

Merge Compared to Union

Merge and Union operations are similar in that they combine objects.  The difference is that Merge simply combines coordinate lists as if each object combined is a new branch while Union utilizes the spatial implications of inside/outside the objects had before being merged.   This can be most clearly seen when areas are combined using Merge or Union.

 

   

 

Consider two overlapping area objects, as seen in the left-most illustration above.   A Merge operation simply combines the coordinate lists of the two objects as two branches.   The coordinate list of the second object treated as a branch results in a "hole" in the region of overlap with a touching "island" where the second branch does not overlap the first branch.   This is a consequence of how coordinate lists are used to define branched area objects.

 

A Union operation considers both original area objects in terms of the spatial definition of what is considered to be "inside" the original area boundary.  That "inside" is retained as if both areas were metal cutouts where the region of overlap between the metal cutouts is welded together in the region of overlap, to form a single "inside" within the new, combined cutout.  Branches are used in Union where area objects do not touch or overlap, so show such a combined, area object as having "islands."

 

Notes

New functions - The list in this topic is intended to be comprehensive but might be not up to date.  New items are often added with updates to Manifold and may appear in the product before they appear in this documentation.   See the list in the query builder tab of the Command Window for an authoritative list of operators, commands and functions.

 

TileGeom functions in Release 9 compared to Release 8 -   Release 9 provides an upgrade for geometry (vector) to raster operations compared to Release 8.  Most of the considerations that follow involve fine details down to the level of individual pixels, to cover cases where very precise vector objects touch only part of a pixel:

 

 

 

TileFillMissingNearest in Release 9 compared to Interpolation functions in Release 8 - The TileFillMissingNearest function is similar to surface interpolation functions in 8, but there are two important differences:

 

 

 

Functions retaining the original tile type - Functions such as TileFill and several other functions retain the original tile type. What does this mean? Consider a simple example:

 

? TileJson(TileFill(TileMake(3, 3, CAST(1 AS UINT8)), 5))

 

The above creates a 3x3 tile of type UINT8 filled with the value 1 in each pixel.  It then refills the tile with the value 5 in each pixel.  Finally, it outputs the result as a JSON string. The result is what we would expect: [ 5, 5, 5, ... ]

 

Consider a variation:

 

? TileJson(TileFill(TileMake(3, 3, CAST(1 AS UINT8)), -1))

 

This creates the same tile as before but then tries to refill it with a value of -1 in each pixel.  The result is: [ 255, 255, 255 ... ].

 

What happened? Because TileFill keeps the original tile type, in this case an unsigned eight bit number, the value of -1 was converted to UINT8 and this produced the value 255, the unsigned eight bit equivalent of the number -1.   

 

Other frequent conversions to keep in mind are from doubles to ints, where values are cut, and from numbers to xN values or vice versa, where values get padded or are cut.

 

Filters - For information on functions that use a <filter> argument or which produce a filter definition matrix, see the How Matrix Filters Work topic.

 

What are the built-in filters? -  Functions that are named beginning with TileFilterDef define a filter tile definition for subsequent use by TileFilter.  To see the filter matrix those functions generate we can use TileJson.  For example, to see what TileFilterDefSquare(1,1) generates using arguments that specify a radius of 1 to get a 3x3 matrix, and a center of 1, we can launch the Command Window and enter:

 

? TileJson(TileFilterDefSquare(1, 1))

 

Press the ! Run button and the Log pane of the Command Window reports:

 

> ? TileJson(TileFilterDefSquare(1, 1))

nvarchar: [

 1, 1, 1,

 1, 1, 1,

 1, 1, 1

]

 

Some of the built-in filter definition functions generate much more complex filter matrix definitions than we would want to keyboard manually.  For example:

 

? TileJson(TileFilterDefEdges(1, 1))

 

Reports:

 

> ? TileJson(TileFilterDefEdges(1, 1))

nvarchar: [

 -0.0009872784326934365, -0.03888148788384807, -0.0009872784326934365,

 -0.03888148788384807, 1, -0.03888148788384807,

 -0.0009872784326934365, -0.03888148788384807, -0.0009872784326934365

]

 

Most filter matrices published on various web sites use simpler forms, or provide fractions in the matrix filter cells instead of long decimal fractions.

 

Normalization - GeomMakeRect is happy to accept the x1,y1 and x2, y2 in non-normalized order, that is, it doesn't matter to the function if we give it the lower left corner followed by the upper right corner so that x1 is less than x2 and y1 is less than y2.   But when GeomBox reports the x4 value for a bounding box it always reports the x4 value in a standard way, in normalized form so that x1 is less than or equal to x2 and y1 is less than or equal to y2.

 

GeomClip - If two geoms touch, their intersection is mathematically non-empty, but might have a lower dimension than the geoms and so be empty in terms of geom type; however, GeomClip must return a geom of the same type as its first argument. For example, two areas that share a corner touch, but intersecting them produces a point, which is not a valid area, and so GeomClip for that case will return NULL.

 

"Par" versions of functions such as GeomOverlayAdjacentPar will be deprecated -  Some functions, such as GeomOverlayAdjacent for example, exist both in single-threaded versions that do not provide an argument for the number of threads to use and also in a fully-parallel version, GeomOverlayAdjacentPar, that provides a <threads> argument to enable specifying how many threads to use.    Such "Par" versions are a temporary measure to get around Manifold's current inability to provide such functions with optional arguments.  Either the function has a <threads> argument or it does not, so two versions of the function are provide to allow one to not offer a <threads> specification and the other one to offer a <threads> specification.   The "Par" versions of functions will be deprecated when optional arguments for functions will appear in Manifold, allowing functions such as GeomOverlayAdjacent to have an optional <threads> argument to control parallel execution.

 

GPGPU - Manifold automatically uses GPU parallelism (see the GPGPU topic) in functions where it makes sense to do so and when workflow is such that it is worth it to dispatch to GPU instead of simply using CPU parallelism.  In many cases both CPU parallelism and GPU parallelism will be used.  For example, all Kriging implementations (standard, median polish, and regression Kriging) use GPU, if available, to compute model parameters together with CPU parallelism in other parts of the function's operation.  GPU cards are so cheap that it doesn't make sense to try to guess when it pays to use GPGPU: simply install a GPU card, at least a cheapo GPU card.  Always.  Do not overthink it.  Just install an NVIDIA GPU card.

 

Why a GPU parallelism limit to radius/border of 8 or less? - Filter functions using a <radius> argument to set the size of the filter matrix applied typically are limited to a radius of 8 or less for GPGPU parallelism, switching to CPU parallelism at a radius of 9 or greater.   Calls to tile functions which use borders of 9 or more pixels likewise automatically dispatch to CPU parallelism.  In both cases, calls dispatched to CPU parallelism can freely intermix with calls dispatched to GPU parallelism.   

 

Those limitations allows more flexible use of a greater range of GPU cards.  Some cards, perhaps older cards or lower cost cards, may have limited memory or earlier generation GPU chips, but they nonetheless can provide very many cores for GPGPU parallel computation.  Manifold makes it possible to use such cards effectively for GPGPU parallelism.  

 

A radius of 8 implies a 17x17, 289-cell matrix, an absurdly huge and almost always an excessively large choice for matrix size.  A radius of 9 or above may indicate a conceptual error or workflow error.   At the same time, use of a radius of 9 or above requires so much GPU-accessible memory that such tasks fit into fewer and fewer cards, even if performance-reducing methods are adopted.   Given a choice between assuring a wide range of GPU cards will always work well, or restricting GPU choice to allow practices that are probably wrong in any event, Manifold chooses to support a wider range of GPU cards, placing the current switch to CPU parallelism at a radius or border of 9.  That may change as CUDA editions evolve.

 

Invisible pixels and filters - A difference in handling invisible pixels between Release 8 and Release 9 emerges when using functions such as TileFilterMax,  TileFilterMajor and similar matrix filter functions:  The surface evaluator tool in 8 was produces a visible pixel if at least one pixel in the vicinity is visible, which could make some invisible pixels visible.  In Release 9 invisible pixels stay invisible and visible pixels generally stay visible.  Visible pixels only turn invisible if non-zero filter coefficients all fall onto invisible pixels.  If the center value for a filter is non-zero, then visible pixels will always stay visible.

 

TileTrace functions - TileTrace functions track the number of different pixel values they encounter, and thus the number of different "bins" for which areas should be created, and stop if that number gets too big.  Currently, the limit is 20,000. Having too many different pixel values usually means that the image has to be preprocessed or that the function has to be called with a higher quantization factor to make the results usable.

 

Z values - All functions support Z values.

 

M values - Functions creating geoms from other formats tolerate M values in formats that have them but ignore those M values, discarding them.

 

Curvilinear objects -  Functions for GML, WKB and WKT support curvilinear objects for all types supported by each format:  circular arcs, ellipsoidal arcs, splines for GML and circular arcs for WKB and WKT.

 

String functions using regular expressions:   See the Regular Expressions topic for allowed syntax for the <regexp> argument.   The <flags> argument must be provided and is either 'i' to ignore case or is 'c' for case matters.

 

Division by zero - returns NULL.

 

All types of values - Operators and functions generally  support all types of values so that, for example, we can use comparison or boolean operators on tiles and not just on scalar values.  

 

Floor and Trunc functions -  The Floor and Trunc functions are similar but different.  Floor, FloorDecs, TileFloor and TileFloorDecs round down towards negative infinity while Trunc, TruncDecs, TileTrunc and TileTruncDecs round towards zero.   For positive values the functions are identical but return different results for negative values.  For example, Floor(-2.3) is -3 while Trunc(-2.3) is -2.

 

Everything Math - For a handy reference to anything in mathematics, see the Wolfram MathWorld site.   Thank you, Wolfram!

 

See Also

Tables

 

Add an Index to a Table

 

Functions

 

Queries

 

Regular Expressions

 

How Matrix Filters Work

 

Command Window

 

Command Window - Query Builder

 

SQL Constants and Literals

 

SQL Statements

 

SQL Operators

 

Aggregate SQL Functions

 

General SQL Functions

 

Coord SQL Functions

 

Geom SQL Functions

 

String SQL Functions

 

Tile SQL Functions

 

Temporary Databases

 

EXECUTE

 

Example: Create and Run a Query -  See how the different parts of a command window operate when creating and running SQL queries.   Includes use of the Log tab as well as the ?expression and !fullfetch commands.

 

Example: Transfer DEM Terrain Heights to Areas in a Drawing - Given a map with an image layer that shows terrain heights taken from a DEM, and a drawing layer that contains areas, using a small SQL query we transfer the average terrain height within each area to that area as a Height attribute for the area. Easy!

 

SQL Example: Process Images with 3x3 Filters -  Shows a step-by-step example of developing an SQL query that takes a query written by the Edit Query button and then modifies that query into a general purpose query that can apply any 3x3 filter.   This makes it easy to use matrix filters we find on the web for custom image processing.   We extend the query by using parameters and adding a function, and then show how it can be adapted to use a 5x5 filter.

 

SQL Example: Process Images using Dual 3x3 Filters  - A continuation of the above topic, extending the example query to utilize two filters for processing, as commonly done with Sobel and Prewitt two filter processing.

 

SQL Example: Process RGB Images using Matrix Filters - A continuation of the above two topics, extending the example query to process three channel, RGB images.

 

SQL Example: Miscellaneous SQL Functions - A variety of small examples using SQL functions.

 

SQL Example: GeomOverlayAdjacent Function - Using the GeomOverlayAdjacent function, an example that shows how this function and similar functions such as GeomOverlayContained, GeomOverlayContaining, GeomOverlayIntersecting and GeomOverlayTouching operate.

 

SQL Example: GeomOverlayTopologyUnion Function - A continuation of the SQL Example: GeomOverlayAdjacent Function example, using the GeomOverlayTopologyUnion function, an example that shows how this function and similar functions such as GeomOverlayTopologyIdentity, GeomOverlayTopologyIntersect and GeomOverlayTopologyUpdate operate.

 

Example: Union Areas - Combine multiple area objects into a single area.   A drawing of French regions shows some regions as more than one area.  We would like each region to be one area so the table of regions has one record per region.

 

SQL Example: Learning to Union Areas in SQL from Edit Query - We learn how to write an SQL query that does a custom Union Areas operation by cutting and pasting from what the Edit Query button automatically generates.

 

Example: Use a Transform Expression to Create Buffers in a Drawing - Use the Expression tab of the Transform pane to create three different sizes of buffers for different lines in a drawing and then automatically create a query which does the same thing.  Includes examples of using the Add Component button and also the Edit Query button.

 

Example: Clip Areas with a Transform Expression - Use the Expression tab of the Transform pane to clip areas in a drawing to fit within horizontal bounds.   Includes examples of using the Add Component button and also the Edit Query button.

 

Example: Transform Templates, Expressions and Queries - We learn to use a function by clicking on a template in the Transform pane, seeing what it does in a preview, looking at the query Manifold creates and then trying out the function in the Expression tab.

 

SQL Example: List Transformation Grids - In this example we use a few snippets of easy SQL to list NTv2 and NADCON transformation grids that are available within the grids.dat compressed collection of transformation grid files.   Grid transformation files can be used when creating custom base coordinate systems, for NADCON / HARN / HPGN and NTv2 high accuracy transformations that use grid files.