Geodata Processing

This page provides on overview of the processing paths that may be applied to geodata, using the Data Processing API. This includes processing of 3rd-party 2D image pixel data, 2D vector shape data, 3D model data as well as Tinman-specific raster data and pyramid data.

Overview

When working with geodata, the initial step is to determine which geodata interface to use, for example Pixel Data or Shape Data.

The next step is to obtain an object that implements the interface, while wrapping the geodata. For example, an IImage or IShape object.

The final step is to combine these geodata objects into a processing pipeline, for example to produce Raster Data and Pyramid Data.

The next sections each contain the following sub-sections, which describe each of the above steps:

Import

Shows how to wrap an existing data source with the API, in order to obtain an instance of a geodata interface. For example:
"Open geo-referenced image file <my-data.tif>."

Consume

Shows how to use the API to modify and combine geodata objects and how to access the resulting geodata. For example:
"Read pixel data after removing border pixels."

Process

Shows ways to assemble geodata objects into a processing pipeline and to otherwise use them in the API. For example:
"Transfer pixel data into a raster or pyramid dataset."
"Create a cubemap texture from a DDS file."

The above classification is ambiguous in some cases, for example: importing 3D model data by extruding 2D shape data could also be seen as processing 2D shape data into 3D model data by extruding it. In these cases, you will usually find the description in the Process step.

The following table shows the geodata interfaces and corresponding links to the documentation on how to obtain geodata objects and how to process them.

Table 1. Geodata interfaces
Geodata Interface Documentation

Pixel data

IImage

See Pixel Images domain model and Pixel Data section.

Shape data

IShape

See 2D Shapes domain model and Shape Data section.

Model data

IModel

See 3D Models domain model and Model Data section.

Raster data

IHeightmap

See Raster overview and Raster Data section.

Pyramid data

IPixelPyramid

See Pyramid overview and Pyramid Data section.

Since geodata is accessed through interfaces, you may implement your own implementations to wrap geodata sources that are not supported by the Tinman 3D SDK.

While combining geodata objects, it is often the case that transformations and conversions need to be performed between geodata objects, possibly involving different geodata interfaces. The following table gives an overview of the most common conversion paths.

Table 2. Common data flow paths
From / To IImage IShape IModel IHeightmap IPixelPyramid

IImage

(1)
(2)

IShape

(3)
(4)
(3)
(3)
(3)

IModel

(5)
(6)

IHeightmap

(7)
(7)
(8)
(7)

IPixelPyramid

(9)
(10)
1 See Pixel Data / Consume section.
2 See Pixel Data / Process section.
3 See Shape Data / Process section.
4 See Shape Data / Consume section.
5 See Model Data / Consume section.
6 See Model Data / Process section.
7 See Raster Data / Process section.
8 See Raster Data / Consume section.
9 See Pyramid Data / Process section.
10 See Pyramid Data / Consume section.

Pipeline Tasks

This section describes the individual tasks of the geodata processing pipeline while referring to the involved APIs. Implementing a geodata processing pipeline for an application or a processing script usually boils down to choosing some processing tasks and to hook them up appropriately.

The GeodataPipeline class is an example for a geodata processing pipeline.
Pipeline Tasks
Figure 1. Pipeline Tasks
§1 - Import one pixel data source to a new raster dataset

This task reads a single pixel data source (for example a GeoTIFF file) and transfers it as a whole to a new rectangular raster dataset, including geo-referencing metadata. Usually, this task is used as an intermediate step that consumes pixel data and stores the results in a raster dataset, so that subsequent tasks may consume and process that raster data efficiently.

This task may be executed implicitly when using §3.
API / Scripting

IImage.ImportPixels / Image.Import

Code Examples

Tutorial_41_Geodata

Geodata Examples

Bennu / Blue Marble 2 / GEBCO / Landsat 7 ETM+

See also

Pixel Data / Process

§2 - Import pixel data sources into a raster dataset

Similarly to §1, this tasks transfers pixel data to a rectangular raster dataset. The difference is that this task reads one or more pixel data sources and transfers the resulting raster data incrementally to an existing dataset. Using this task requires that the size and geo-reference of the target dataset have already been defined.

Use the validate parameter to check that the geo-referencing information is consistent and that pixels and raster samples are aligned properly.
§3 - Project data from rectangular to cubemap datasets

With §1 and §2, geodata can be transferred into rectangular raster datasets. Such raster data may only be combined at runtime when the same geo-reference is used. In order to be able to combine raster data freely, datasets must be transformed from rectangular to cubemap, which replaces geo-references that use projected coordinate systems with geo-references that use plain geodetic datums (for example WGS84).

This task may optionally include an implicit execution of §1, in order to import a pixel data source into a temporary raster dataset, which is then projected to a cubemap dataset. Analogously to raster data, pyramid data may also be projected from rectangular to cubemap with this task.

Raster data data cannot be projected on-the-fly during runtime, because raster samples need to be re-arranged. This does not apply to pyramid data, which is well-suited for re-projection at runtime.
§4 - Convert raster data to pyramid data

With this task, raster data may be converted to pyramid data, either during a separate data preprocessing step or on-the-fly during runtime of the application.

Raster data provides content only for the bottom-most pyramid level. The other levels are generated by exploiting the partitioning scheme of raster data, which provides optimal efficiency for reading samples but might also introduce aliasing effects, which are comparable to nearest-point filtering vs. tri-linear filtering on a mipmap-chain.

To avoid aliasing effects, slicing may be used to show pyramid data only for those levels which do not have apparent aliasing effects. Also, task §5 may be used to copy the bottom-most pyramid level to a separate dataset and then compute the upper levels with a proper downsampling filter.
§5 - Copy raster and pyramid data

This task copies raster or pyramid data, while optionally performing an operation on the data being copied. For example, raster data may be blurred and downsampling may be performed on pyramid data, in order to generate pyramid tiles of upper levels.

§6 - Update raster and pyramid data at runtime

Raster data and pyramid data may be updated at runtime, by using the IHeightmap and IPixelPyramid interfaces. Doing so will trigger notifications via IHeightmap.OnUpdated resp. IPyramidBase.OnUpdated, which are consumed by the Low-level Terrain API, the High-level Terrain API and the Scene API. As result, the 3D-terrain will adapt automatically to data updates.

The tasks §1, §2, §3 and §5 delegate to this task and may thus be used as well to update data at runtime.
§7 - Replace raster and pyramid data at runtime

When using the Low-level Terrain API, High-level Terrain API or Scene API, raster data must be specified at creation time, by providing a IHeightmap object (see MeshOptions and SceneOptions), which cannot be replaced with another object later. Pyramid data, on the other hand, may be specified at runtime, by providing a IPixelPyramid object, which may be replaced by another object at any time.

To allow raster data to be replaced at runtime, a proxy may be used: by providing a IHeightmapProxy object at creation time, different IHeightmap objects may be set as content later, which will trigger a data update analogously to task §6.

Replacing pyramid data at runtime is straight-forward, just use the appropriate API to specify a new IPixelPyramid or ITexelPyramid object.

§8 - Combine raster and pyramid data at runtime

A geodata pipeline will usually produce a number of IHeightmap and IPixelPyramid objects, by using the tasks §1 through §5. These objects represent raster and pyramid data of different resolution and regions. This task combines such data, so that low-resolution data is replaced with high-resolution data and separate regions are merged together. These operations are usually performed on-the-fly during runtime.

Raster and pyramid data can only be combined if the same geo-reference is used. It is advisable to use cubemap data, where the geo-reference reduces to a geodetic datum, such as WGS84.

File Data

File Data
Figure 2. File Data

Geodata files are commonly referenced with Path objects and/or plain string values. In addition, the IFileData interface may be used to provide the binary content of a geodata file in a more flexible way.

Table 3. File data
API Scripting Description

FileData.For

Bytes

Uses the given binary content.

FileData.For

Path

Uses the content of the given file.

IFileData.Zip

Zip

Uses the content of an entry in a ZIP archive.

IFileData.OpenStream

-

Reads the file data as a binary data stream.

Subsequent sections will show only the IFileData interface when referencing geodata files. In most cases, there are additional method overloads for specifying string values and Path objects directly.

Procedural Data

Procedural Data
Figure 3. Procedural Data

Procedural data can be generated with the Tinman 3D SDK by using so called noise functions. A noise function takes a three-dimensional input vector and produces a smooth pseudo-random output value for it, i.e. the output value is deterministic and depends only on the input vector.

There are three types of noise functions:

All noise functions are derived from the INoiseFunction interface, which provides common semantics:

  • Noise function objects are typically arranged in an object graph, which involves arithmetic operations and other transformations.

  • To minimize the complexity of such object graphs, noise function objects provide a way to simplify the object graph structure, usually according to mathematical rules like A + 0 = A or A * 0 = 0.

  • Constant noise functions always produce the same output value regardless of the input vector. This information is crucial to simplification.

All noise function objects use the low-level noise functions of the ProceduralUtil class.

The following table shows how to obtain noise function objects.

Table 4. Noise function factories
API Scripting Description

ColorFunction.Constant

Color.Constant

Outputs the given constant color value.

ScalarFunction.Cellular

Cellular

Outputs Cellular noise scalar values.

ScalarFunction.Constant

Scalar.Constant

Outputs the given constant scalar value.

ScalarFunction.One
ScalarFunction.Zero

Scalar.Constant

Outputs the constant scalar value 1.0 resp. 0.0.

ScalarFunction.Perlin

Perlin

Outputs Perlin noise scalar values.

VectorFunction.Constant

Vector.Constant

Outputs the given constant vector value.

VectorFunction.Gradient

Vector.Gradient

Outputs gradient vector values of Perlin noise scalar values.

VectorFunction.Input

Input

Outputs the result of a linear transformation of the input vector value.

The following table shows how to combine noise function objects.

Table 5. Noise functions operators
API Scripting Description

IColorFunction.Add
IColorFunction.Blend
IColorFunction.Mul
IColorFunction.Op
IColorFunction.Sub

Color.Op

Applies the given operator on the input value(s).

INoiseFunctionOps.Linear

Scalar.Constant
Scalar.Op
Color.Constant
Color.Op
Vector.Constant
Vector.Op

Applies a linear function on each component of the output value.

INoiseFunctionOps.Simplify

-

Simplifies the underlying object graph structure of the noise object.

INoiseFunctionOps.Transform

Scalar.Transform
Color.Transform
Vector.Transform

Uses a vector function to transform the input value.

IScalarFunction.Abs
IScalarFunction.Add
IScalarFunction.Atan
IScalarFunction.Div
IScalarFunction.Log
IScalarFunction.Max
IScalarFunction.Min
IScalarFunction.Mul
IScalarFunction.Neg
IScalarFunction.Op
IScalarFunction.Pow
IScalarFunction.Recip
IScalarFunction.Sin
IScalarFunction.Sqr
IScalarFunction.Sqrt
IScalarFunction.Sub

Scalar.Op

Applies the given operator on the input value(s).

IScalarFunction.Clamp

Clamp

Clamps the output value to the given range.

IScalarFunction.ColorRamp

Noise.Color.Ramp

Uses the output value of a scalar function to perform a color-ramp lookup, in order to produce the output color value.

IScalarFunction.DivInv

-

Applies the given operator on the input value(s), swapping the operands.

IScalarFunction.MultiRidged

MultiRidged

Computes noise over multiple octaves.

IScalarFunction.MultiSum

Scalar.MultiSum

Computes noise over multiple octaves.

IScalarFunction.NaN

Nan

Replaces not-a-number and +/- infinity with the given values.

IScalarFunction.PowInv

-

Applies the given operator on the input value(s), swapping the operands.

IScalarFunction.Select

Select

Uses the output value of a scalar function to perform cubic interpolation on an array of aggregated scalar functions.

IScalarFunction.Spline

Scalar.Spline

Uses the output value of a scalar function to evaluate a spline curve.

IScalarFunction.SubInv

-

Applies the given operator on the input value(s), swapping the operands.

IScalarFunction.Whirl

Whirl

Uses a scalar function to compute an offset for each component of the input value.

IVectorFunction.Add
IVectorFunction.Mul
IVectorFunction.Norm
IVectorFunction.Op
IVectorFunction.Sub

Vector.Op

Applies the given operator on the input value(s).

IVectorFunction.MultiSum

Vector.MultiSum

Computes noise over multiple octaves.

Pixel Data

Pixel data in the Tinman 3D SDK is defined as a rectangle that is made of square pixels, where each pixel may either be void (i.e. not representing any data) or represent a color value with separate red, green, blue and alpha (transparency) channels, each having 24-bits of integer precision. These are called normalized pixel values and range from 0 to 16777215 (i.e. 224-1).

Pixel data sources (for example image files) use varying data types and value ranges for their raw pixel data, for example 8-bit unsigned integers for sRGB color channel values or 32-bit floating-point values for elevation values in metres. The mapping from the raw pixel range to the normalized pixel range is retained in IImageInfo.Range, so that it may be taken into account in subsequent processing steps.

For additional information, please refer to Software Architecture / Pixel Images.

Import

Pixel Data / Import
Figure 4. Pixel Data / Import

Importing pixel data means to wrap a pixel data source in an IImage object, in order to be able to access the image metadata and image content.

Table 6. Common pixel data sources
API Scripting Description

Image.Constant

Image.Constant

Generates an image with constant pixel values.

Image.File

Image.File

Reads pixel data from an image file.

Image.Random

Image.Random

Generates an image with random pixel data.

Image.Raw

Raw

Reads raw pixel data from binary data.

Consume

Pixel Data / Consume
Figure 5. Pixel Data / Consume

Consuming pixel data means to read the content of an IImage object by using the ImageReader object that has been obtained via IImage.ReadImage. Pixel data is retrieved by calling IImageReader.ReadScanline repeatedly, once for each pixel row.

Various on-the-fly conversions and transformations of pixel data may be performed by wrapping an IImage or IImageReader object in another one, which the modifies the pixel values of the Scanline object. The IImageOps interface defines a set of built-in pixel data modifications.

Table 7. Common pixel data consume tasks
API Scripting Description

IImage.Sharpen

Sharpen

Applies a sharpening filter to the pixel data.

IImageOps.Adjust

Image.Adjust

Adjusts brightness and/or saturation.

IImageOps.AlphaToCoverage

AlphaToCoverage

Replaces transparent pixels with void pixels.

IImageOps.ChannelToIntensity

IntensityFrom

Extracts a channel as a grayscale image.

IImageOps.Clip

Image.Clip

Extracts a sub-rectangle as an image.

IImageOps.Crop

Crop

Replaces border pixels with void pixels.

IImageOps.Function

Function

Applies a function on the pixel values of a channel.

IImageOps.IntensityToChannel

IntensityTo

Replaces a channel with pixel values of a grayscale image.

IImageOps.Invert

Image.Invert

Inverts the pixel values of a channel.

IImageOps.Op

Image.Op

Combines two images using the chosen color operation.

IImageOps.Pad

Image.Pad

Duplicates edge pixels to increase the image size.

IImageOps.Scale

Image.Scale

Scales an image to a different size.

IImageOps.SetCoverage

Image.Coverage

Reinterprets the pixel data with the given pixel coverage.

IImageOps.SetGamma

Gamma

Configures gamma correction for pixel values.

IImageOps.SetGeoref

Image.Georef

Reinterprets the pixel data with the given geo-reference.

IImageOps.SetLayer

Image.Layer

Specifies the heightmap layer to associate with the pixel data.

IImageOps.SetNoData

NoData

Specifies the pixel value to interpret as void.

IImageOps.SetRange

Image.Range

Configures the raw and normalized pixel ranges.

IImageOps.Smooth

Smooth

Applies a smoothing filter to the pixel data.

IImageOps.ToCoverage

Image.Coverage

Resamples the pixel data to the given pixel coverage.

Image.Combine

Image.Combine

Uses separate images per channel to assemble a new image.

Image.EncodeNormals

EncodeNormals

Encodes normal vectors in the color channels of an image.

Image.Grid

Grid

Arranges multiple images in a grid to assemble a new image.

Process

Pixel Data / Process
Figure 6. Pixel Data / Process

Pixel data is processed into Raster Data by transferring its pixel values into a IHeightmap object as HeightmapSample values. Various transformations may be applied during this step, usually to adjust the pixel value range and to resample / project pixels when moving from one geo-reference to another.

To export pixel data for consumption by 3rd-party software, the IImageWriter interface may be used. Please refer to the built-in ImageFormat objects for details on the supported file formats.

Table 8. Common pixel data processing tasks
API Scripting Description

IImage.ImportPixels

Image.Import

Creates a new PXB file or a HGT dataset and copies all pixel data to it, without performing resampling or reprojection.

IImage.ProjectPixels

Image.Project

Transfers all pixel data into an existing IHeightmap object, while performing resampling and reprojection, as required by the geo-references.

IImage.ReadTexture

-

Reads the pixel data directly as a texture resource, avoiding redundant decoding and encoding steps where possible.

IImage.WriteFile

Write

Exports all pixel data into an image file of the specified file format.

IHeightmap.ImportPixels

Heightmap.Import

Copies pixel data to an existing IHeightmap object, without performing resampling or reprojection.

Another way to process pixel data is to feed it into other parts of the Tinman 3D SDK, either as IImage objects or as derived data objects, for example ColorBuffer objects (image manipulation) or TexelBuffer (GPU rendering) objects. Here is a list of possible API calls:

Shape Data

Shape data in the Tinman 3D SDK is defined as a signed distance field (SDF) in a two-dimensional coordinate system, with an optional geo-reference and optional geometry data (vertices, edges, triangles, polygon contours).

Based on this definition, shapes may be implicit (signed distance <= 0), points (only vertices), graphs (only vertices and edges), polygons (only contours made of vertices and edges) or meshes (only vertices and triangles).

For additional information, please refer to Software Architecture / 2D Shapes.

Import

Shape Data Import
Figure 7. Shape Data / Import

Importing shape data means to wrap a shape data source in a IShape object, in order to be able to access the shape metadata, the shape geometry and the shape distance field.

Table 9. Common shape data sources
API Scripting Description

IMarkingBuilder

-

Creates shapes for pavements and ground markings.

Shape.ArcInner
Shape.ArcOuter
Shape.Arrow
Shape.Circle
Shape.Curve
Shape.GeographicPolygon
Shape.Grid
Shape.Oval
Shape.Polygon
Shape.Polyline

-

Creates a pre-defined shape.

Shape.Box

Box

Creates a simple axis-aligned box shape.

Shape.CheckerBoard

Checkerboard

Creates a procedural checkerboard shape.

Shape.Circle

Circle

Creates a procedural circle shape.

Shape.Geometry

Geometry

Creates a shape from the specified geometry.

Shape.File

Shape.File

Reads shape data from a shape file.

Here are some other API members that provide IShape objects:

Consume

Shape Data Consume
Figure 8. Shape Data / Consume

Consuming shape data means to use the signed distance field and the geometry data (vertices, edges, triangles, polygon contours), optionally taking into account the shape geo-reference.

There are various conversions and transformations that may be applied to IShape objects, for example signed distance field manipulation, projection to other geo-references and conversion between shape types (implicit, points, graph, mesh, polygon).

Many IShape implementations compute data lazily, at the time it is requested. In these cases, computation may be enforced with IShapeOps.PrepareLazy. In the following table, deferred indicates lazy computations and immediate indicates computations that are performed instantly.

Table 10. Common shape data consume tasks
API Scripting Description

IShapeOps.Absolute

deferred

Absolute

Modifies the signed distance field:

Distanceout = abs(Distancein)

IShapeOps.Convert

immediate

-

Converts the shape from one type to another:

implicit - points - graph - polygon - mesh

IShapeOps.Invert

deferred

Shape.Invert

Modifies the signed distance field:

Distanceout = -Distancein

IShapeOps.Maximum

deferred

Maximum

Modifies the signed distance field:

Distanceout = max(Distancein_1, Distancein_2)

IShapeOps.Minimum

deferred

Minimum

Modifies the signed distance field:

Distanceout = min(Distancein_1, Distancein_2)

IShapeOps.Offset

deferred

Shape.Offset

Modifies the signed distance field:

Distanceout = Distancein-1 + offset

IShapeOps.Outline

deferred

-

Modifies the signed distance field:

Distanceout = abs(Distancein) - width / 2

IShapeOps.RenderPrepare

immediate

-

Converts the shape to a graph and mesh shape, for subsequent rendering with lines and triangles.

IShapeOps.TransformCoordinateSystem

deferred

Shape.Georef

Transforms the shape geometry from one geo-reference to another.

IShapeOps.TransformCoordinates

deferred

Shape.Matrix

Transforms the shape geometry with an affine transformation.

IShapeOps.TransformCubemap

deferred

Cubemap

Transforms the shape geometry to the faces of the geographic cubemap frame.

IShapeOps.TransformGeometry

immediate

-

Transforms the shape geometry from one geo-reference to another.

Process

Shape Data Process
Figure 9. Shape Data / Process

The most common way to process shape data is to perform on-the-fly rasterization at runtime, based on the signed distance field. This is used to generate Raster Data and Pyramid Data, for example.

Table 11. Common shape data processing tasks
API Scripting Description

IShape.ImportCSH

Shape.Import

Reads the shape data and writes it to a CSH file.

IShapeRasterizerFactory.Rasterizer

-

IShapeExtruder.Extrude

-

Constructs 3D geometry by extruding the geometry of a 2D shape.

ModelGeometry.Shape

-

Converts a 2D shape to planar 3D geometry.

Another way to process shape data is to feed it into other parts of the Tinman 3D SDK. Here is a list of possible API calls:

Model Data

Model Data
Figure 10. Model Data

Model data in the Tinman 3D SDK is defined as an object graph which assembles hierarchical 3D models from basic components, such as 2D textures and 3D geometry, in a way that is comparable to glTF 2.0.

For additional information, please refer to Software Architecture / 3D Models.

Import

Model Data Import
Figure 11. Model Data / Import - part 1

Importing model data means to construct individual model components and then to assemble these into a hierarchical 3D model. This can be done explicitly by creating each component from scratch while specifying all required data. There are also various factories for constructing commonly used model data directly. Additionally, ready-to-use model data may be loaded from 3D model files.

Table 12. Common model data sources - part 1
API Scripting Description

ModelFormat.ReadModel
Model.Read

Model.Read
Load

Creates a IModelReader object will can be used to load model data, optionally providing methods for data manipulation and correction, if the object is an instance of ModelReader.

Model.Load

-

Loads the given model data and returns the root IModel object.

Model.Chunk

-

Builds a IModel object for an exported terrain mesh chunk.

Model Data Import
Figure 12. Model Data / Import - part 2
Table 13. Common model data sources - part 2
API Scripting Description

ModelGeometry.Build

-

Creates a ModelGeometryBuilder object that can be used to build model data programmatically.

ModelGeometry.Box
ModelGeometry.Capsule
ModelGeometry.Cone
ModelGeometry.Cylinder
ModelGeometry.Disc
ModelGeometry.Generic
ModelGeometry.Hemisphere
ModelGeometry.Line
ModelGeometry.Sphere
ModelGeometry.SphereIco
ModelGeometry.Tube

-

Creates a IModelGeometrySimple object using a pre-defined factory method.

ModelGeometry.Dynamic

-

Creates a IModelGeometryDynamic object which can be used to hold model geometry data that may change at runtime.

ModelGeometry.Shape

-

Creates a IModelGeometrySimple object from a IShape object.

ModelGeometry.Wrap

-

Wraps user-defined model geometry data in a IModelGeometry object.

ModelTexture.For1

Texture.Constant

Creates a IModelTexture that has a uniform color.

ModelTexture.For2
ModelTexture.For3

Model.Texture.Encode

Creates a IModelTexture that encodes the pixel data of an IImage object.

ModelTexture.For4

Txb

Creates a IModelTexture from the contents of a TexelBuffer, storing it as an in-memory TXB file.

ModelTexture.For5

Pxb

Creates a IModelTexture from the contents of a ColorBuffer, storing it as an in-memory PXB file.

ModelTexture.RenderTarget

-

Creates a IModelTexture that references the output texture resource of a IRenderTarget.

Here are some other API members that provide model data objects:

Consume

Model Data Consume
Figure 13. Model Data / Consume

Consuming model data means to access the content of the model data objects that are contained in a 3D model hierarchy.

Various on-the-fly conversions and transformations of model data may be performed by wrapping IModel, IModelGeometry, IMaterial and IModelTexture objects in other ones, which the modifies the data.

Model data objects may compute data lazily, at the time it is requested. In these cases, computation may be enforced with IModel.PrepareLazy. In the following table, deferred indicates lazy computations and immediate indicates computations that are performed instantly.

Table 14. Common model data consume tasks
API Scripting Description

IModel.UseGeometryInstancing

immediate

-

Attaches a GPU instance buffer to the model, thus enabling instanced rendering.

IModelGeometry.Instanced

deferred

-

Attaches a GPU instance buffer to the geometry, thus enabling instanced rendering.

IModelGeometry.Optimized

deferred

-

Removes unused vertices and reorders the remaining ones for improved rendering performance.

IModelGeometry.Reduced

deferred

-

Reduces floating-point precision from 64-bit to 32-bit, in order to reduce memory consumption and storage space.

IModelGeometry.Transform

deferred

-

Transforms the vertices using the specified Mat4D matrix value.

IModelTexture.Invert

deferred

Texture.Invert

Inverts the given color channels.

IModelTexture.NormalMap

deferred

Texture.Normals

Converts a bump-map texture into a normal-map texture.

IModelTexture.Swizzle

deferred

Texture.Swizzle

Replaces or swaps color channels, according to the given operands.

Process

Model Data Consume
Figure 14. Model Data / Process

Usually, processing model data means to either render 3D models with a GPU (see ModelRenderer) or to perform spatial queries on the 3D geometry (see ISpatialQuery).

To export model data for consumption by 3rd-party software, the ModelFormat.WriteModel method may be used. Please refer to the built-in ModelFormat objects for details on the supported file formats.

Table 15. Common model data processing tasks
API Scripting Description

ModelScanner

-

Performs ray-casting on the geometry of a 3D model, in order to produce Raster Data.

Another way to process model data is to feed it into other parts of the Tinman 3D SDK. Here is a list of possible API calls:

Raster Data

Raster data is primarily used to generate vertices for building terrain meshes. Please refer to Terrain Overview for more information.

Import

Raster Data Import
Figure 15. Raster Data / Import

Importing raster data means to wrap a raster data source in a IHeightmap object. This step is often preceded with a pixel data processing step or a shape data processing step, which has produced the source raster data. Using Procedural Data, raster data may also be generated at runtime.

Please refer to the GeodataPipeline class as an example for a simple processing pipeline.
Table 16. Common raster data sources
API Scripting Description

Heightmap.Dataset

Heightmap.Dataset

Opens a dataset in read-only or read/write mode.

HeightmapBuilder.Constant

Heightmap.Constant

Creates a heightmap with constant sample values.

HeightmapBuilder.Dataset

Heightmap.Dataset

Creates a heightmap dataset. Storage space is only used for actual data.

HeightmapBuilder.Memory

Heightmap.Memory

Creates an in-memory heightmap. Memory is only used for actual data.

HeightmapBuilder.Procedural

Heightmap.Procedural

Uses Procedural Data to generate samples at runtime.

HeightmapBuilder.Proxy

-

Creates a proxy heightmap which allows to swap the heightmap content later, by choosing another heightmap to wrap (see IHeightmapProxy.Content).

HeightmapBuilder.Shapes

Heightmap.MapShapes

Creates a heightmap that generates samples at runtime, by performing rasterization of map shapes (see IHeightmapShape.ShapeAdd).

Consume

Raster Data Consume
Figure 16. Raster Data / Consume

Consuming raster data means to assemble IHeightmap objects at runtime in order to access or transfer heightmap sample data (see HeightmapSample, HeightmapSamples and HeightmapRegion).

Table 17. Common raster data consume tasks
API Scripting Description

IHeightmap.Augment

Merge
Heightmap.Constant

Merges a heightmap with a constant data, in order to fill in missing heightmap layers.

IHeightmap.CopySamples

Heightmap.Copy

Copies samples from one heightmap to another while optionally applying a custom copy operation on the samples.

IHeightmap.GetSample
IHeightmap.GetSamples
IHeightmap.GetRegion

-

Reads samples from a heightmap.

IHeightmap.Material

Heightmap.Material

Generates data for the material layer by applying color-keys to the texture layer.

IHeightmap.Projector

-

Creates a HeightmapProjector object that can be used to transfer samples between two heightmaps while performing required conversions and resampling, taking into account geo-referencing information.

IHeightmap.ProjectSamples

Heightmap.Project

Transfers samples from one heightmap to another in a background operation while performing required conversions and resampling, taking into account geo-referencing information.

IHeightmap.UpdateRegion

-

Writes samples to a heightmap.

IHeightmapOps.Border

Border

Fits a rectangular heightmap in a square one while smoothing the borders with a given fall-off.

IHeightmapOps.Clip

Heightmap.Clip

Uses the coverage layer of the second heightmap to remove data from the first heightmap.

IHeightmapOps.Combine

Heightmap.Combine

Combines the data of two heightmap, using the specified combine operations.

IHeightmapOps.Merge

Merge

Merges the data of two heightmaps, taking into account the coverage layers.

IHeightmapOps.Proxy

-

Creates a placeholder heightmap that can have its content replaced later.

IHeightmapOps.Scale

Heightmap.Scale

Scales a heightmap to a different raster size.

IHeightmapOps.Split

Split

Extracts a single layer from a heightmap.

IHeightmapOps.Swizzle

Heightmap.Swizzle

Swaps material IDs in the material layer.

IHeightmapOps.TransformRange

Heightmap.Range

Transforms the vertical coordinates of the heightmap (i.e. elevation and displacement).

IHeightmapOps.UseColorRamp

Heightmap.Ramp

Uses a color-ramp to generate data for the texture layer, based on the elevation layer.

HeightmapGrinder

-

A helper object that automatically merges heightmaps of different resolutions.

Process

Raster Data Process
Figure 17. Raster Data / Process

Processing raster data means to transform it to other data (e.g. terrain brushes, mesh chunks or pyramid data) or to use it for real-time terrain rendering.

Table 18. Common model data processing tasks
API Scripting Description

Brush.InputHeightmap

-

A terrain painting brush that sources data from a heightmap.

Geocentric.Vertical

-

Uses the heightmap for geocentric computations that involve gravity-related height or height above surface.

IHeightmap.ToImage

HeightmapRegion

Reads a rectangular region of a heightmap as pixel data.

IHeightmapOps.ToPyramid

Wrap

Generates pyramid data for the given heightmap.

MeshChunkBuilder.MeshChunkBuilder

-

Uses the heightmap for building 3D models for selected terrain sectors.

MeshOptions.Heightmap

-

Uses the heightmap for a terrain in the Low-level Terrain API or the High-level Terrain API.

SceneOptions.TerrainGeoid
SceneOptions.TerrainHeightmap

-

Uses the heightmap for a terrain in the Scene API.

Another way to process raster data is to feed it into other parts of the Tinman 3D SDK. Here is a list of possible API calls:

Pyramid Data

Pyramid data is primarily used to generate textures for terrain meshes. Please refer to Terrain Overview for more information.

Import

Pyramid Data Import
Figure 18. Pyramid Data / Import

Importing pyramid data means to obtain a IPixelPyramid object that wraps some pyramid data source, in order to be able to access the contained pyramid tiles by reading and/or writing ColorBuffer data.

Table 19. Common pyramid data sources
API Scripting Description

BingMapsPyramid

BingMaps

Streams BingMaps data.

ColorBufferPyramid.For

Buffer

Creates a pyramid that wraps the given pixel data.

CountingPyramid

-

Creates a pyramid that counts accesses to pyramid tiles, which is useful to track billable transactions for online services.

GoogleMapsPyramid

GoogleMaps

Streams GoogleMaps data.

HeightmapRegionPyramid

Region

Creates a pyramid that shows regions for which raster data is available.

MBTilesPyramid

MBTiles

Opens an .mbtiles pyramid dataset in read-only mode.

OpenStreetMapPyramid

OpenStreetMap

Streams OpenStreetMaps data.

PixelPyramid.Dataset

Pyramid.Dataset

Opens a dataset in read-only or read/write mode.

PixelPyramidBuilder.Constant

Pyramid.Constant

Creates a pyramid with constant pixel values.

PixelPyramidBuilder.Dataset

Pyramid.Dataset

Creates a pyramid dataset. Storage space is only used for actual data.

PixelPyramidBuilder.Memory

Pyramid.Memory

Creates an in-memory pyramid. Memory is only used for actual data.

PixelPyramidBuilder.Shapes

Pyramid.MapShapes

Creates a pyramid that generates samples at runtime, by performing rasterization of map shapes (see IPixelPyramidShape.ShapeAdd).

UrlPatternPyramid

Url

Accesses a web-service that delivers pyramid data, for example WMS or WMTS.

Consume

Pyramid Data Import
Figure 19. Pyramid Data / Consume

Consuming pyramid data means to assemble IPixelPyramid objects at runtime in order to access or transfer pyramid data (see ColorBuffer).

Table 20. Common pyramid data consume tasks
API Scripting Description

IPixelPyramid.Cache

Pyramid.Cached

Wraps a pyramid in an in-memory cache or a file-based cache.

IPixelPyramid.Combine

Pyramid.Combine

Combines the data of two pyramids, using the specified combine operations.

IPixelPyramid.CopyTiles

Pyramid.Copy

Copies pyramid tiles from one pyramid to another one.

IPixelPyramid.Downsample

Downsample

Computes pixel data for empty pyramid tiles by downsampling the four child tiles.

IPixelPyramid.Draw

-

Aggregates another pixel pyramid and performs custom drawing on the pixel data on its pyramid tiles.

IPixelPyramid.GetTileData

-

Reads pixel data for the given pyramid tile.

IPixelPyramid.SetTileData

-

Writes pixel data for the given pyramid tile.

IPixelPyramid.Slice

Slice

Slices a pyramid so that pixel data is returned only for a given range of pyramid levels.

IPixelPyramid.ToFullSize

Size

Scales a pyramid to the given full size (i.e. the size of the bottom-most level).

IPixelPyramid.ToTilePad

Pyramid.Pad

Specifies the amount of tile padding for the pyramid.

IPixelPyramid.ToTileSize

Tile

Specifies the tile size of the pyramid.

IPixelPyramid.Unproject

Unproject

Performs re-projection of pixel data in order to convert a rectangular pyramid to a cubemap pyramid.

PixelPyramidGrinder

-

A helper object that automatically merges pyramids of different resolutions.

Process

Pyramid Data Process
Figure 20. Pyramid Data / Process

Processing pyramid data means to transform it to other data (e.g. texture data or mesh chunks) or to use it for real-time terrain rendering. The IPixelPyramid and ITexelPyramid interfaces both represent pyramid data: the former provides data as ColorBuffer objects, whereas the latter provides data as TexelBuffer objects.

Table 21. Common pyramid data processing tasks
API Scripting Description

IPixelPyramid.EncodePixels

Pyramid.Texture.Encode

Encodes a pixel pyramid into a texel pyramid.

IPixelPyramid.ToImage

PyramidRegion

Reads a rectangular region of a pyramid as pixel data.

ITexelPyramid.Cache

Texture.Cached

Wraps a texel pyramid in a file-based cache.

ITexelPyramid.DecodePixels

-

Decodes a texel pyramid into a pixel pyramid.

MapViewWidget.Pyramid

-

Uses a texel pyramid for 2D map rendering.

MeshChunkBuilder.Texture

-

Uses a pixel pyramid to generate textures for 3D models of terrain mesh chunks.

TerrainLayerSlot.Set

-

Uses a pixel pyramid for real-time 3D terrain rendering.

TextureAtlas.PyramidIdAllocate

-

Uses a texel pyramid to provide texture data for a GPU-based texture atlas.

TextureLayer.ContentAt

-

Uses a pixel pyramid as a texture layer in a scene.

Another way to process pyramid data is to feed it into other parts of the Tinman 3D SDK. Here is a list of possible API calls: