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.

Figure 1. Pipeline Tasks

Task List: §1 - Import one pixel data source to a new raster dataset
§2 - Import pixel data sources into a raster dataset
§3 - Project data from rectangular to cubemap datasets
§4 - Convert raster data to pyramid data
§5 - Copy raster and pyramid data
§6 - Update raster and pyramid data at runtime
§7 - Replace raster and pyramid data at runtime
§8 - Combine raster and pyramid data at runtime

§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.

API / Scripting: IHeightmap.ImportPixels / Heightmap.Import
Code Examples: ConfigValueBrowser_Tinman_AddOns
Geodata Examples: ASTER GDEM 3 / ASTER WBD 1 / GMTED2010 / MODIS Water Mask / NED 1/3" / NED 1/9" / Mars Orbiter Camera / Mars Orbiter Laser Altimeter / Planets / Racing Track / Skybox / World Machine
See also: Pixel Data / Process

§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.

API / Scripting: IImage.ProjectPixels / Image.Project
IHeightmap.ProjectSamples / Heightmap.Project
IPixelPyramid.Unproject / Unproject
Code Examples: GeodataPipeline / Tutorial_41_Geodata
Geodata Examples: Antarctica / ASTER GDEM 3 / ASTER WBD 1 / Bennu / Blue Marble 2 / EGM2000 / EGM96 / Elevation1 / GEBCO / GMTED2010 / HiRISE / Landsat 7 ETM+ / Lunar Recon. Orbiter Camera / Mars Digital Image Model / Mars Express / Mars Orbiter Camera / MODIS Water Mask / Mars Orbiter Laser Altimeter / NED 1/3" / NED 1/9" / geodata-examples.adoc#new_horizons / New Horizons / swissALTI3D
See also: Pixel Data / Process
Raster Data / Consume
Pyramid Data / Consume

§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.

API / Scripting: IHeightmapOps.ToPyramid / Wrap
Code Examples: Example_Application / Tutorial_14_Texturing / Tutorial_22_Game / Tutorial_23_Earth / Tutorial_24_Moon / Tutorial_25_Mars / Tutorial_26_Bennu / Tutorial_28_Objects / Tutorial_31_Showcase / Tutorial_41_Geodata / Tutorial_42_MeshChunk / Tutorial_52_MapBrowser
See also: Raster Data / Process

§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.

API / Scripting: IHeightmap.CopySamples / Heightmap.Copy
IPixelPyramid.CopyTiles / Pyramid.Copy
IPixelPyramid.Downsample / Downsample
Code Examples: Example_GeodataProcessing
See also: Raster Data / Consume
Pyramid Data / Consume

§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.

API / Scripting: IHeightmap.UpdateRegion / -
IPixelPyramid.SetTileData / -
See also: Raster Data / Consume
Pyramid Data / Consume

§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.

API / Scripting: IHeightmapProxy.Content / -
ITextureCacheDependent.SetTexture / -
TerrainLayerSlot.Set / -
TextureLayer.Content / -
Code Examples: Example_Application / Tutorial_14_Texturing / Tutorial_23_Earth / Tutorial_31_Showcase
See also: Raster Data / Import
Pyramid Data / Process

§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.

API / Scripting: IHeightmapOps.Combine / Heightmap.Combine
IHeightmapOps.Merge / Merge
IPixelPyramid.Combine / Pyramid.Combine
HeightmapGrinder / -
PixelPyramidGrinder / -
Code Examples: Example_GeodataProcessing / GeodataPipeline / Tutorial_22_Game / Tutorial_23_Earth / Tutorial_24_Moon / Tutorial_25_Mars / Tutorial_26_Bennu / Tutorial_28_Objects / Tutorial_30_SceneViewWidget / Tutorial_41_Geodata / Tutorial_52_MapBrowser
See also: Raster Data / Consume
Pyramid Data / Consume

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

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:

IColorFunction (produces color values)
IScalarFunction (produces scalar values)
IVectorFunction (produces vector values)

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. 2²⁴-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

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

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

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

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

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: `Distance_out = abs(Distance_in)`
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: `Distance_out = -Distance_in`
IShapeOps.Maximum deferred	Maximum	Modifies the signed distance field: `Distance_out = max(Distance_{in_1}, Distance_{in_2})`
IShapeOps.Minimum deferred	Minimum	Modifies the signed distance field: `Distance_out = min(Distance_{in_1}, Distance_{in_2})`
IShapeOps.Offset deferred	Shape.Offset	Modifies the signed distance field: `Distance_out = Distance_in-1 + offset`
IShapeOps.Outline deferred	-	Modifies the signed distance field: `Distance_out = abs(Distance_in) - 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

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	-	Constructs a IShapeRasterizer, using the specified factory. HeightmapRegion (Raster Data): Shape.RasterizerFactory¹ Shape.RasterizerFactory² ColorBuffer (Pyramid Data) Shape.RasterizerFactory⁴ Shape.RasterizerFactory⁵ DistanceBuffer Shape.RasterizerFactory³
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

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

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.

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.For¹	Texture.Constant	Creates a IModelTexture that has a uniform color.
ModelTexture.For² ModelTexture.For³	Model.Texture.Encode	Creates a IModelTexture that encodes the pixel data of an IImage object.
ModelTexture.For⁴	Txb	Creates a IModelTexture from the contents of a TexelBuffer, storing it as an in-memory TXB file.
ModelTexture.For⁵	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:

For IModel objects:
- IModelGeometrySimple.ToModel
- ModelResult.Model
For IModelTexture objects:

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

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:

For IModel objects:
For IModelReader objects:
- ConfigValueBrowser_Tinman_AddOns.BrowseModelReader
- ModelWidget.LoadModel
For IModelTexture objects:

Raster Data

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

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

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

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

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

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

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: