TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

Workshop Application

The Tinman 3D Workshop Application provides users with a sandbox GUI environment for exploring the features of the Tinman 3D SDK.

The Tinman 3D SDK offers its functionality by providing native C# and C++ APIs, which can be used separately. A subset of this functionality is exposed via the ConfigScript API (see Reference), which the Workshop wraps in a slick GUI.

Tinman 3D Workshop Application

Log Messages

A logfile is written to each time the Workshop runs (tinman3d_workshop.log). The full path to the logfile is indicated in the console output.

2017-10-07 06:29:44 [C] Location of application log file:
                        c:\Users\Pikantos\tinman3d_workshop.log                                 [Tinman.Workshop.App]

Errors are indicated with [E], warnings with [W].

During normal operation, neither errors nor warnings should occur.

Main Ribbon

The main ribbon of the Workshop provides these functions:

Application Menu

Shows the application menu (see About Box).

Show Project Explorer

Activates and shows the tool window.

New Project

Creates a new empty project. (*.twp).

Show Type Explorer

Activates and shows the tool window.

Open Project

Opens an existing project (*.twp).

Show Inspector Tool

Activates and shows the tool window.

Save All

Saves all changes (project and scripts).

Show Browser Tool

Activates and shows the tool window.

New Script

Adds a new empty script to the project.

Show Processor Tool

Activates and shows the tool window.

Add Script

Adds an existing script to the project.

Show Message List

Activates and shows the tool window.

Remove Script

Removes a script from the project.

Save Window Layout

Saves the current window layout.

Load Window Layout
Loads the previously saved window layout

Default Layout

Restores the default window layout.

Tinman 3D Workshop Application - Main Window Ribbon

Tool Windows

The following tool windows are used by the Workshop:

Project Explorer

The Project Explorer shows the model tree of the currently loaded Tinman 3D Workshop Project (*.twp).

The first tree level displays the Tinman 3D Workshop Script Files (*.tws) that are associated with the project. The ConfigScript class is used to parse the script files. The scripts of a project at put into a ConfigDomain instance, which allows them to reference each other's members.

The second tree level lists the members (see ConfigMember) of each script.

Commands:

Collapse All

Collapses all nodes of the project tree.

Expand All

Expands all nodes of the project tree.

Show Internal Members?

Shows or hides internal script members (see ConfigMember.IsIntern).

Project File

Shows the name of the current project file.

Double-click to browse to the project directory.

Context Menu:



Show Help F1
Show the documentation of the type of the script member.
Jump to Code F3
Shows the source code of the member in its script window.
Send to Inspector F4
Inspects the script member (see ConfigValueBrowser.Inspect).
Send to Browser F5
Browses the script member (see ConfigValueBrowser.Browse).


Run with Processor F6
Processes the script member (see IOperation).  
Jump to filesystem F9
Opens the folder that contains the script file.
Close  
Closes the Script Editor window of the member.
Tinman 3D Workshop - Project Explorer Tool

Script Editor

The Script Editor is used to edit script files.

Context Menu:

Show Help

F1

Show the documentation of the type of the expression.

Find in Project F2
Locates the item in the Project Explorer.
Send to Inspector F4
Inspects the script member (see ConfigValueBrowser.Inspect).
Send to Browser F5
Browses the script member (see ConfigValueBrowser.Browse).
Run with Processor F6
Processes the script member (see IOperation).
Import from file... F8
Imports a file into the script as a new member.
Jump to filesystem F9
Opens the folder that contains the script file.
Close  
Closes the source code window of the selected script file.
Tinman 3D Workshop - Script Editor

The following bindings from keys to edit actions are defined:

Clipboard/Undo Edit Actions

Key Edit Action

Ctrl + C

Copies the selected text to the clipboard.

If the selection is empty, the whole text line containing the cursor is copied.

Ctrl + Ins
Ctrl + X

Cuts the selected text to the clipboard.

If the selection is empty, the whole text line containing the cursor is cut.

Shift + Del
Ctrl + L Cuts the whole text line containing the cursor to the clipboard.
Ctrl + V Replaces the selected text with the clipboard content.
Shift + Ins
Ctrl + Y Performs one redo step.
Ctrl + Shift + Z
Ctrl + Z Performs one undo step.

Deletion Edit Actions

Key Edit Actions
Backspace  
Shift + Backspace  
Ctrl + Backspace  
Del  
Ctrl + Shift + L  
Ctrl + Del  

Insertion Edit Actions

Key Edit Actions
Enter  
Shift + Enter  
Ctrl + Enter  
Ctrl + Shift + Enter  

Miscellaneous Edit Actions

Key Edit Actions
Ctrl + I  
Tab  
Ctrl + U  
Ctrl + Shift + U  
Shift + Tab  
Ctrl + Shift + I  
Insert  
Ctrl + T  
Ctrl + Shift + T  
Shift + Alt + T  
Alt + Up  
Alt + Down  

Movement Edit Actions

Key Edit Actions
Down  
Up  
Left  
Right  
Ctrl + Left  
Ctrl + Right  
Home  
End  
Ctrl + Home  
Ctrl + End  
Page Up  
Page Down  
Ctrl + Page Up  
Ctrl + Page Down  
Ctrl + ]  

Scroll Edit Actions

Key Edit Actions
Ctrl + Down  
Ctrl + Up  

Selection Edit Actions

Key Edit Actions
Ctrl + Num-  
Ctrl + Num+  
Escape  
Shift + Down  
Shift + Up  
Shift + Left  
Shift + Right  
Ctrl + Shift + Left  
Ctrl + Shift + Right  
Shift + Home  
Shift + End  
Ctrl + Shift + Home  
Ctrl + Shift + End  
Shift + Page Up  
Shift + Page Down  
Ctrl + Shift + Page Up  
Ctrl + Shift + Page Down  
Ctrl + A  
Ctrl + Shift + W  
Ctrl + Shift + ]  
Shift + Alt + Down  
Shift + Alt + Up  
Shift + Alt + Left  
Shift + Alt + Right  
Ctrl + Shift + Alt + Left  
Ctrl + Shift + Alt + Right  

Message List

The Message List windows shows all errors and warnings that have been generated for the script files in the project or the value being browsed resp. inspected in the Browser resp. Inspector Tool.

Errors and warnings are generated by using the Validator class and friends.

An error message (see ValidateMessageType).

Use the toggle button to show/hide error messages.

Messages from the Browser Tool, regarding the value that is currently being browsed.

Use the toggle button to show/hide Browser Tool messages.

A warning message (see ValidateMessageType).

Use the toggle button to show/hide warning messages.

Messages from the Inspector Tool, regarding the value that is currently being inspected.

Use the toggle button to show/hide Inspector Tool messages.

An informative message.

Use the toggle button to show/hide information messages.

Messages from the Script Editor windows, regarding syntax and semantic errors in the script.

Use the radio button to choose which messages to show:
All scripts in the project, only Open scripts, only the Current script or None.

Tinman 3D Workshop - Message List

Type Explorer

The Type Explorer shows all ConfigType instances, and provides filtering and search functions.

Commands:

Collapse All

Collapses all nodes of the type tree.

Expand All

Expands all nodes of the type tree.

Show By Name

Shows the config types by their full name tree, e.g.Tinman.Operation.Delete.

Show Alphabetically

Shows the config types by their flat names, e.g. Delete.

Show By Type

Shows the config types by their inheritance tree.

Show Classes

Shows / hides ClassType instances that are no structure types.

Show Structs

Shows / hides ClassType instances that are structure types.

Show Enums

Shows / hides EnumType instances.

Search In Tree

Filters the current tree content, showing only those items that match the given input.

Context Menu:



Show Help F1
Show the documentation of the type of the script member.
Jump to Code F3
Shows the source code of the member in its script window.
Send to Inspector F4
Inspects the script member (see ConfigValueBrowser.Inspect).
Send to Browser F5
Browses the script member (see ConfigValueBrowser.Browse).


Run with Processor F6
Processes the script member (see IOperation).  
Jump to filesystem F9
Opens the folder that contains the script file.
Close  
Closes the Script Editor window of the member.
Tinman 3D Workshop - Type Explorer

Help Browser

The Help Browser shows the documentation of the config types (see ConfigDoc).

Tinman 3D Workshop - Help Browser

Inspector Tool

The Inspector Tool shows the ConfigValue hierarchy of the inspected value. The lower part of the property grid shows the textual representation of the selected ConfigValue.

Legend:

Indicates that a field of a ConfigValue that has a non-default value.
Indicates that a field of a ConfigValue that has a default value.
Indicates an external field of a ConfigValue, i.e. the field value is computed by native code instead of being configured by script.

Context Menu:

Show Help

Show the documentation of the type of the inspected value.

Find in Project
Locates the inspected value in the Project Explorer.
Jump to Code
Shows the source code of the inspected value.
Send to Inspector
Inspects the browsed value (see ConfigValueBrowser.Inspect).
Import from file...
Imports a file into the Browser for being browsed.
Jump to filesystem
Opens the folder that contains the file that is being browsed.
Close
Closes the Browser view, which disposes the browsed value.
Tinman 3D Workshop - Inspector Tool

 

Browser Tool

The Browser Tool runs an IApplication object, using a WPF application host.

Context Menu:

Show Help

F1

Show the documentation of the type of the inspected value.

Find in Project F2
Locates the inspected value in the Project Explorer.
Jump to Code F3
Shows the source code of the inspected value.
Send to Browser F5
Browses the inspected value (see ConfigValueBrowser.Browse).
Import from file... F8
Imports a file into the Inspector for being inspected.
Jump to filesystem F9
Opens the folder that contains the file that is being inspected.
Close  
Closes the Inspector view, which disposes the inspected value.
Tinman 3D Workshop - Browser Tool

 

Processor Tool

The Processor Tool shows the IOperation objects that have been created and run from script members.

Commands:

Running jobs

Click toggle button to show / hide running jobs.

Click the job item to cancel it (you will be prompted first).

Finished jobs

Click toggle button to show / hide finished jobs.

Click the job item to close it (you will be prompted first).

Cancelled jobs

Click toggle button to show / hide canceled jobs.

Click the job item to close it (you will be prompted first).

Failed jobs

Click toggle button to show / hide failed jobs.

Click the job item to display the error message.

Action

Close jobs

Choose a drop-down item to quickly close job items.

Running jobs cannot be closed, they must be cancelled first.

Context Menu:



Show Help
Show the documentation of the type of the job item.
Find in Project
Locates the job item in the Project Explorer.
Jump to Code
Shows the source code of the job item in its script window.
Send to Inspector
Inspects the job item (see ConfigValueBrowser.Inspect).
Close
Closes the job item.
Tinman 3D Workshop - Processor Tool

Dialog Windows

The following sections describe the various dialog windows that are used by the Workshop.

Dialog Windows can be interactive; in this case there will be hyperlinks in the dialog content, which can be clicked to perform the described action.

About Box

The About Box window shows a system information dump (see TinmanModule.SystemInfo).

You can reach the About Box from the Application Menu.

About Box - Tinman 3D Workshop Application

The Abount Box can be used to quickly determine which 3rd-party libraries and plugins have been detected.

For the Workshop, this primarily affects the set of available file formats (see FileFormat) and config value browsers (see ConfigValueBrowser).

Tinman.Terrain v1.0 - 2017/10/06

  [...]

  ImageFormat
    'Any' : Automatic image format
    'BMP' : Built-in support for BMP
    'DDS' : Built-in support for DDS
    'JPG' : Built-in support for JPEG
    'PNG' : Built-in support for PNG
    'PXB' : Tinman 3D PiXel Buffer
    'TGA' : Built-in support for TGA
    'TIFF' : Built-in support for TIFF, GeoTIFF, BigTIFF
    'TXB' : Tinman 3D TeXel Buffer
    'GDAL' : GDAL 2.2.1, released 2017/06/23
    'GDAL+PROJ' : GDAL 2.2.1, released 2017/06/23

  ShapeFormat
    'Any' : Automatic shape format
    'CSH' : Tinman 3D Compiled SHape
    'SHP' : ESRI Shapefile

Tinman.AddOns v1.0 - 2017/10/06

  [...]

  ModelFormat
    'Any' : Automatic model format
    'CMH' : Tinman 3D Compiled Model Hierarchy
    'LAS' : LASer (LAS) File Format 1.3
    'OBJ' : Wavefront OBJ
    'OFF' : Object File Format

  ConfigValueBrowser:
    'Tinman'

[...]

Tinman.Workshop v1.0 - 2017/10/06

  AppData  : c:\ProgramData\Tinman3D\Tinman.Workshop
  UserData : c:\Users\Pikantos\AppData\Local\Tinman3D\Tinman.Workshop

  GeoRegistry : EPSG 9.1 / Tinman 1.0

The Workshop stores some settings in its UserData directory:

Licence Key

A valid User, Site or Academic licence key is required to run the Workshop.

Licence keys are taken from the TINMAN_3D_LICENCEKEY environment variable and from the %LOCALAPPDATA%\Tinman3D\Tinman.Workshop\licence-key.txt file.

The Licence Key dialog is displayed if no licence key has been found or if none of the licence keys is valid (e.g. expired).

Tinman 3D Workshop - Licence Key Dialog

Unsaved Changes

If you close a script, project or the Workshop, you will be prompted if there are any unsaved changes.

You can toggle which changes to save and which ones to discard, by clicking on the displayed dialog actions.

Tinman 3D Workshop - Unsaved Changes Dialog

Conflicting Changes

When modifying script files both in the Workshop and in some external editor, conflicting changes may occur. In this case this dialog will be displayed.

Use the dialog action to choose which external changes to apply and which ones to discard.

Tinman 3D Workshop - Conflicting Changes Dialog

File Import

When importing a file into a script, the Browser or the Inspector, this dialog will be displayed.

Use the dialog actions to choose how to import the file.

Tinman 3D Workshop - File Import Dialog

Error Report

If an unexpected error occurs, this dialog will be displayed.

A detaild error description will have been copied to the clipboard when this dialog is shown. The same information can be found in the logfile.

Tinman 3D Workshop - Error Report Dialog

Plug-ins

When starting up, the Tinman 3D Workshop Application scans its working directory for plug-in files:

To be loaded successfully by the Workshop, a plug-in must meet these requirements:

Once loaded, a plug-in will contribute the following entities to the Workshop:

Command-line arguments

The following tokens can be specified via the command-line (separated by whitespaces):