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.

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)

The 3rd-party libraries in this directory tree have been created using Visual Studio 2022, requiring Windows 7 or newer.

Assimp - Open Asset Import Library

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

bin/win.any/assimp5.x32.dll
bin/win.any/assimp5.x64.dll
bin/win.x32/assimp5.x32.dll
bin/win.x64/assimp5.x64.dll

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

bin/win.any/

.NET Framework 4.8 executables (AnyCPU)

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

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

bin/win.x32/

Windows 32-bit executables (Windows 7 or newer)

bin/win.x64/

Windows 64-bit executables (Windows 7 or newer)

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.021.dat (current)

  • 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.0, which contains only those header files that are required to build the C++ code of the Tinman.AddOns.Assimp component.

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.

lib/win.any/

Cross-platform .NET Standard 2.0 library assemblies (AnyCPU)

These library assemblies have been obfuscated.

lib/win.x32/

Windows 32-bit DLLs (Windows 7 or newer)

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

lib/win.x64/

Windows 64-bit DLLs (Windows 7 or newer)

Only the library of the Tinman.Licence component is contained in the download. All other libraries must be compiled by using one of the contained C++ 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, dx11, dx12, gl41, gles30).

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.