Getting Started

This page will help you get started quickly with using the Tinman 3D SDK.

The following instructions refer to the Tinman 3D SDK release packages. If you have downloaded a preview package, please refer to the readme.txt file.

Prerequisites

These prerequisites may need to be installed separately in order to use all SDK components:

Download and Installation

To download and install the Tinman 3D SDK, please follow these steps:

  1. Read and accept the Terms and Conditions.

  2. Download the packages (see Release Notes).

  3. Validate the MD5 checksums (optional).

  4. Unzip the package archives into a directory of your choice. All package archives share a common folder structure. You can install additional packages by copying them into the main package.

File associations

To associate Tinman 3D specific file types with the Workshop Application, the tinman3d.file_associations script can be used:

Command-line options
> tinman3d.file_associations
....
Syntax:
  show    Show current file types and associations.
  add     Add file types and associate with '.\tinman3d_workshop.exe'.
  remove  Remove file types and associations.
On Windows, the script must be run with administrator privileges.

First Steps

We recommend the following steps as a run-through of the Tinman 3D SDK.

  1. Run the Demo Application.

    You can watch many features of Tinman 3D live in action here.

    bin/win.*/tinman3d_demo.exe

  2. Browse the Geodata Examples.

    This will show you how geodata is imported into Tinman 3D, from a users perspective.

    data/geo/*

    To browse the Geodata Examples in the Workshop Application, open this project file:

    src.twp/geodata_examples.twp

  3. Read the Developer Guide.

    The guide explains important concepts and aspects of the SDK, providing you with the starting points you need for your own development work.

  4. Browse the Demo Application source code.

    Here you can see how the Tinman 3D SDK is used for development.

    ide.cpp/vs/Tinman3D.SDK.Cpp.sln
ide.cs/vs/Tinman3D.SDK.CSharp.sln

  5. Browse the API reference.

    You will find the documentation of the entire API of the Tinman 3D SDK there. The APIs for C# and C++ are identical.

  6. Browse the Scripting reference.

    Here you can see how the built-in scripting system of Tinman 3D looks like. For information about the scripting language, please refer to Scripting Overview.

Directory Structure

This sections shows the directory structure that is shared by all Tinman 3D SDK packages.

The root directory contains command-line script files and configuration files:

The Demo Application uses a virtual filesystem with the root selector "Engine:" for accessing its content files. The filesystem content is defined by a variable named resources in the configuration file, which is an array of Mapping objects.

bin/

You can find the Tinman 3D executables in this directory tree. For details on the subdirectory structure, please refer to Architectures.

Use the project files in ide.cs/ and ide.cpp/ to rebuild the executables.
Tinman 3D executables

tinman3d_bakery (Licence Bakery)
tinman3d_demo (Demo Application)
tinman3d_demo_mfc (Demo Application, MFC / C++)
tinman3d_demo_winforms (Demo Application, WinForms / C#)
tinman3d_demo_wpf (Demo Application, WPF / C#)
tinman3d_workshop (Workshop Application)
tinmanpc (Geodata Processor)

Some 3rd-party libraries in this directory tree have been created using Visual Studio 2022, requiring Windows 7 or newer. These libraries may be replaced by newly built versions, at any time.

Assimp - Open Asset Import Library

These libraries are required by the Tinman.AddOns.Assimp component:

bin/*/assimp5.x32.dll
bin/*/assimp5.x64.dll

Please refer to AssimpModelFormat for details on how to build these libraries from source.

Some 3rd-party libraries in this directory have been taken from their official release packages. These libraries may be replaced by newer release versions, at any time.

SDL - Simple DirectMedia Layer

These Windows libraries have been taken directly from the official release packages and are required by the Tinman.AddOns.SDL component:

bin/*/SDL?.x32.dll
bin/*/SDL?.x64.dll

On Linux, please use your package manager to install SDL. If a SDL library has been found at runtime, there will be a registered IApplicationWindowFactory that supports the Type_SDL2 or Type_SDL3 flag.

SQLite

These Windows libraries have been taken directly from the official release packages and are required by the Tinman.AddOns.SQLite component:

bin/*/sqlite3.x32.dll
bin/*/sqlite3.x64.dll

On Linux, please use your package manager to install SQLite.

codex/

The pre-configured Code-X Workflow for the Demo Application is provided in this directory.

data/

Holds the geo registry files for the EPSG Geodetic Parameter Dataset:

  • epsg-11.025.dat (current)

  • epsg-11.021.dat

  • epsg-11.017.dat

  • epsg-11.012.dat

  • epsg-11.008.dat

  • epsg-9.9.1.dat (legacy)

In general, the current geo registry file should be used. Older files should only be used if necessary, for example to retain specific application behaviour.

data/demo/

Content assets of the Demo Application.

data/geo/

The Geodata Examples and processed raster datasets.

data.bulk/

Downloaded geodata for offline use (optional).

The directory structure of data/ and data.bulk/ is identical.

Files that exist in this directory will be used instead of the online HTTP versions.

doc/

The Tinman 3D SDK documentation (this manual).

ext/

This directory holds source files of third-party libraries.

ext/src.cpp/assimp

This is a stripped down version of Assimp 5.4.3, which contains only those header files that are required to build the C++ code of the Tinman.AddOns.Assimp component.

ext/src.cpp/sdl

This is a header-only version of SDL, which is required to build the C++ code of the Tinman.AddOns.SDL component, if static linkage has been configured at compile-time.

ide.cpp/cmake/

CMake project file for the C++ version of the Tinman 3D SDK.

  • CMakeLists.txt

This is the default project file of the SDK.

The C++ binary libraries are not included in the download. Use this project file to compile your own binaries. You may adjust the compiler and linker options according to your needs.

ide.cpp/cmake.full/

CMake project file for the C++ version of the Tinman 3D SDK.

  • CMakeLists.txt

This is the full source code project file of the SDK.

The C++ binary libraries are not included in the download. Use this project file to compile your own binaries. You may adjust the compiler and linker options according to your needs.

ide.cpp/vs/

Visual Studio solution for the C++ version of the Tinman 3D SDK.

  • Tinman3D.SDK.Cpp.sln
    This is the default solution of the SDK.

  • Tinman3D.SDK.Full.Cpp.sln
    This is the full source code solution of the SDK.

The C++ binary libraries are not included in the download. Use this solution to compile your own binaries. You may adjust the compiler and linker options according to your needs.

ide.cs/vs/

Visual Studio solution for the C# version of the Tinman 3D SDK.

  • Tinman3D.SDK.CSharp.sln
    This is the default solution of the SDK.

  • Tinman3D.SDK.Full.CSharp.sln
    This is the full source code solution of the SDK.

Use this solution to build the Demo Application and the Geodata Processor for framework targets other than .NET Framework 4.8, for example .NET Core 3.1 or .NET 6.0+.

ide.hlsl/vs/

Visual Studio solution for the HLSL shaders that are included in the Tinman 3D SDK.

lib/

Contains the dynamic link libraries of the Tinman 3D SDK. For details on the subdirectory structure, please refer to Architectures.

Only the C++ library of the Tinman.Licence component is contained in the download. All other libraries must be compiled by using one of the contained IDE projects.

src.cpp/

C++ source code files, structured by SDK component.

Files and directories that the '.Full.' name tag belong to the full source code version of the SDK.

src.cs/

C# source code files, structured by SDK component.

Files and directories that the '.Full.' name tag belong to the full source code version of the SDK.

src.fx/

The GPU shader repository, structured by language (hlsl, glsl) and graphics API (dx9 …​ dx12, gl41 …​ gl46, gles30 …​ gles32).

Example 1. GPU shader repository for Direct3D 11

src.fx/hlsl.dx11

src.twp/

The Workshop Application project for the Geodata Examples.

src.xml/

Content for the built-in help system of the Demo Application.

The help system is based on the TextDocument class.

temp/

This directory is used for caching and storing settings.

Architectures

The bin/ and lib/ directories share the same structure, which is explained in this section.

linux.x32/

Linux libraries and executables for the 32-bit x86 processor architecture

linux.x32-arm/

Linux libraries and executables for the 32-bit ARM processor architecture

linux.x64/

Linux libraries and executables for the 64-bit x86_64 processor architecture

linux.x64-arm/

Linux libraries and executables for the 64-bit ARM processor architecture

macos/

Universal binaries of the macOS libraries and executables

net48/

.NET Framework 4.8 executables (AnyCPU)

Use Mono 6+ to run these executables on non-Windows machines.

The following executables are Windows-specific:

  • tinman3d_demo_wpf

  • tinman3d_workshop

net8.0/

.NET 8.0 (AnyCPU)

The following executables are Windows-specific:

  • tinman3d_demo_winforms

  • tinman3d_demo_wpf

  • tinman3d_workshop

The other executables will run on any system that has .NET installed.

Use the solutions in ide.cs/vs/ to build the executables for other framework targets.

netstandard2.0/

.NET Standard 2.0 (AnyCPU)

These library assemblies have been obfuscated.

win.x32/

Windows 32-bit libraries and executables (Windows 7 or newer) for the x86 processor architecture

win.x32-arm/

Windows 32-bit libraries and executables (Windows 7 or newer) for the ARM processor architecture

win.x64/

Windows 64-bit libraries executables (Windows 7 or newer) for the x86_64 processor architecture

win.x64-arm/

Windows 64-bit libraries and executables (Windows 7 or newer) for the ARM processor architecture