Workshop Application

How to download and run

Go to the Public Downloads and get this executable:

  • tinman3d_workshop.exe

The executable is self-contained and can be run without prior installation. It

Please refer to Getting Started for more information.

The Workshop provides users with a sandbox GUI environment for exploring the features of the Tinman 3D SDK, which offers its functionality through native C# and C++ APIs. A subset of this functionality is exposed via scripting, which the Workshop in turn exposes through an interactive user interface, in form of a simple Integrated Development Environment (IDE).

Almost all features of the Workshop are implemented with the Tinman 3D SDK, so the same features can easily be integrated into other applications.
Developer info

These sections contain information for developers regarding the implementation of a feature.

screenshot
Figure 1. Workshop Application

Getting Started

You can start the Workshop by running its self-contained executable. Apart from copying the executable onto your machine, no other installation steps are required.

The Workshop is a WPF application and requires the .NET Framework.

The Workshop executable is included in the binaries folder of the Tinman 3D SDK package:

bin/win.any/tinman3d_workshop.exe

The Workshop executable may also be downloaded separately, so you do not have to download the whole package to get it.

Additional native libraries may be required by Tinman 3D SDK components or 3rd-party plug-ins. These must be present somewhere on the native library search path. If a native library is missing, the corresponding feature will not be available when running the Workshop.

If you are unsure where to put the native libraries, just put them into the same directory as the tinman3d_workshop.exe file.
Native libraries of Tinman.AddOns.Assimp component
bin/win.any/assimp5.x32.dll
bin/win.any/assimp5.x64.dll

You may register file associations for common Tinman 3D file formats, so that these files will be opened with the Workshop. Please refer to Getting Started for details.

Additional information about running the Workshop is available here:

Free Evaluation

A User, Site or Academic licence is required to activate all features of the Workshop.

The Evaluation licence allows to use the Workshop with a limited feature set.

When running in evaluation mode, the (evaluation) tag is visible in the title bar of the application window and a log message is output on startup:

...
2022-04-22 13:41:54 [C] c:\Users\...\tinman3d_workshop.log [Tinman.Workshop.App]
2022-04-22 13:41:56 [C] Running in evaluation mode.        [Tinman.Workshop.App]
...

The following features are not contained in the limited feature set:

Data Export

Export of terrain data (i.e. geo-referenced raster or vector data, vector data, 3D geometry, 3D scenes) to non-proprietary formats (e.g. glTF, GeoTIFF).

Plug-ins

Loading of custom Workshop plug-ins.

User Interface

The user interface of the Workshop has a simple structure.The main window is made of a single toolbar ribbon at the top and a number of dockable tool windows below.

The tool window docking can be customized, for example by rearranging the tool windows within the main window or by distributing tool windows to separate dock container windows.

If the window layout has become cluttered or messed up, for example after a resolution change or after changing monitors, use the Toolbar  Default Window Layout command to get back to the default layout.

The HOME section of the main toolbar is described below.

main toolbar
Figure 2. Workshop Application - Toolbar

The toolbar can be accessed with keyboard chords. Press Alt to begin a chord, the available shortcut keys will appear as overlays on the toolbar.

Use the global hotkey Ctrl+S to trigger the Toolbar  Save All action.

Press F1 to trigger the Toolbar  Show Help Browser action for the current context.

Table 1. Toolbar commands

Project / Scripts

Tools

icon app menu

Application Menu
Shows the application menu.

icon project explorer

Show Project Explorer
Activates and focuses the tool window.

icon new project

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

icon type explorer

Show Type Explorer
Activates and focuses the tool window.

icon open project

Open Project
Opens an existing project (*.twp).

icon help browser

Show Help Browser
Activates and focuses the tool window.

icon save all

Save All
Saves all changed project and script files.

icon inspector

Show Inspector Tool
Activates and focuses the tool window.

icon new script

New Script
Creates a new empty script (*.tms).

icon browser

Show Browser Tool
Activates and focuses the tool window.

icon add script

Add Script
Opens an existing script (*.tms).

icon processor

Show Processor Tool
Activates and focuses the tool window.

icon remove script

Remove Script
Removes a script from the project.

icon message list

Show Message List
Activates and focuses the tool window.

Layout

icon save window layout

Save Window Layout
Saves the current window layout.

icon restore window layout

Restore Window Layout
Restores the saved window layout.

icon default window layout

Default Window Layout
Applies the default window layout.

Tool Windows

This section describes the tool windows of the Workshop.

Project Explorer

The Project Explorer tool shows the model tree of the currently loaded project file (*.twp).

It can be activated with the Alt+H+X keyboard chord.

tool project explorer
Figure 3. Workshop Application - Project Explorer

The first tree level displays the script files (*.tms) that are associated with the project.

The second tree level lists the members of each script.

There are pre-defined scripts that are included automatically in every project:

icon small project file ::Tinman

This is a script which provides general-purpose utility functions.

icon small project file ::Tutorial

This is the tutorial script, see Scripting Overview.

Double-clicking a model tree node will trigger the Project Explorer  Context Menu  Jump to Code action.
Developer info

A ConfigDomain object is maintained for the project and populated with a ConfigScript object for each script, to allow scripts to reference members in other scripts.

The member list is obtained via ConfigScript.GetMembers.

Use ConfigScript.Tinman to build the pre-defined ::Tinman script.

The following toolbar commands are available in the tool window:

Table 2. Project Explorer commands

icon collapse all

Collapse All
Collapses all nodes of the project tree.

icon show intern

Toggle Private Members
Shows or hides private script members.

icon expand all

Expand All
Expands all nodes of the project tree.

icon project file

Project File
Double-click to browse to the project directory.

Developer info

Use ConfigMember.IsIntern to check if a member of a script is private.

These actions are available from the Project Explorer  Context Menu (open with right-lick) of the items in the model tree:

Table 3. Project Explorer context menu

icon help browser

Show Help
Shows the documentation of the selected item in the Help Browser.

F1

icon jump to code

Jump to Code
Shows the source code of the selected item in the Script Editor.

F3

icon inspector

Send to Inspector
Evaluates the script member value and shows it in the Inspector Tool.

F4

icon browser

Show in Browser
Evaluates the script member value and shows it in the Browser Tool.

F5

icon processor

Run with Processor
Evaluates the script member value and runs it in the Processor Tool.

F6

icon jump to filesystem

Jump to filesystem
Opens the folder that contains the script file.

F9

icon close

Close
Closes the script window in the Script Editor.

Developer info

The Project Explorer  Context Menu  Send to Inspector action is implemented with ConfigValueBrowser.Inspect.

The Project Explorer  Context Menu  Show in Browser action is implemented with ConfigValueBrowser.Browse.

The Project Explorer  Context Menu  Run with Processor action uses IOperation.RunBackground.

Script Editor

The Script Editor tool shows a source code editor tab for each open script in the project.

To open a script of the current project, double-click a script or script member node in the Project Explorer or use a Context Menu  Jump to Code action.

To close a script tab, middle-click the tab caption or use the Script Editor  Context Menu  Close action. Closing a tab with unsaved changes will show the Unsaved Changes dialog.

tool script editor
Figure 4. Workshop Application - Script Editor

(1) Source code editor tab caption, showing the script filename
(2) Visual tag for editor tabs with unsaved changes
(3) Text column indicator
(4) Drop-down menu for selecting an open script
(5) Gizmo to drag-split the editor area
(6) Visual tag for script validation result
(7) Text row indicator
(8) Source code editor area with caret and selection
(9) Yellow indicator bar for tracking unsaved changes
(10) Green indicator bar for tracking saved changes
(11) Visual tag for script members and validation messages

Drag & drop the editor tab captions (1) to rearrange the tabs and move them between docking windows.

Drag the split gizmo (5) to split the source code editor area vertically. A second gizmo is located at the lower-left corner, drag it to split the editor area horizontally.

Click the validation result tag (6) to jump to the Message List. Hover with the mouse to display the number of validation messages in a tooltip popup.

Error and warning messages are indicated with red and yellow squiggle underlines in the editor area (8). Hover with the mouse to display the messages in a tooltip popup.

After saving a script, the yellow change markers (9) will turn green.

When closing a source code editor tab, the undo history is cleared and the green change markers (10) disappear.

Context Menus

These actions are available from the Script Editor  Context Menu (open with right-click in the editor area), for the script member at the caret:

Table 4. Script Editor context menu

icon help browser

Show Help
Shows the documentation of the selected member in the Help Browser.

F1

icon project explorer

Find in Project
Shows the model node of the selected member in the Project Explorer.

F2

icon inspector

Send to Inspector
Evaluates the script member value and shows it in the Inspector Tool.

F4

icon browser

Show in Browser
Evaluates the script member value and shows it in the Browser Tool.

F5

icon processor

Run with Processor
Evaluates the script member value and runs it in the Processor Tool.

F6

icon import from file

Import from file
Imports a file and creates a new script variable for it.

F8

icon jump to filesystem

Jump to filesystem
Opens the file or folder that corresponds to the selected member.

F9

icon close

Close
Closes the source code editor tab.

Developer info

The Script Editor  Context Menu  Send to Inspector action is implemented with ConfigValueBrowser.Inspect.

The Script Editor  Context Menu  Show in Browser action is implemented with ConfigValueBrowser.Browse.

The Script Editor  Context Menu  Run with Processor action uses IOperation.RunBackground.

These actions are available from the editor tab context menu (open with right-click on the editor tab caption):

Table 5. Editor tab context menu

Close

Closes the active source code editor tab.

Close Others

Closes all source code editor tabs in the current group except the active one.

Close Tab Group

Closes all source code editor tabs in the current group.

Close All Documents

Closes all source code editor tabs in all groups.

Float

Detaches the active source code editor tab into a floating window.

Pin

Pins the active source code editor tab (pinned tabs appear up-front).

New Horizontal Tab Group
New Vertical Tab Group

Moves the active source code editor tab to a new group.

Move to Next Tab Group
Move to Previous Tab Group

Moves the active source code editor tab to another group.

Key Bindings and Mouse Gestures

The following mouse gestures are available within the source code editor area:

Table 6. Mouse Gestures
Gesture Command

LeftClick

Place caret at click location.

LeftDouble-Click

Select the word at the click location.

RightClick

Place caret at click location and open the editor context menu.

LeftDrag

Select text in line mode.

Alt+LeftDrag

Select text in block mode.

Wheel

Scroll up and down.

Ctrl+Wheel

Increase or decrease the editor font size.

The following keys are bound to source code editor commands:

Table 7. Key Bindings
Key Command

Clipboard / Undo

Ctrl+C

Ctrl+Ins

Copy the currently selected text to the clipboard.

Ctrl+X

Shift+Del

Cut the currently selected text to the clipboard.

Ctrl+L

Cut the text of the current view line to the clipboard.

Ctrl+V

Shift+Ins

Paste the text from the clipboard into the editor.

Ctrl+Y

Ctrl+Shift+Z

Perform a redo operation.

Ctrl+Z

Perform an undo operation.

Deletion

Backspace

Shift+Backspace

Delete the currently selected text or the previous character.

Ctrl+Backspace

Delete text to the beginning of the previous word.

Del

Delete the currently selected text or the next character.

Ctrl+Shift+L

Delete the current view line.

Ctrl+Del

Delete text to the beginning of the next word.

Insertion

Enter

Shift+Enter

Insert a line break at the caret position.

Ctrl+Enter

Insert a new line above the caret position.

Ctrl+Shift+Enter

Insert a new line below the caret position.

Miscellaneous

Tab

Insert a tab at the caret.

Shift+Tab

Remove a tab at the caret.

Ctrl+U

Make the selection all lower-case.

Ctrl+Shift+U

Make the selection all upper-case.

Insert

Toggle overwrite mode.

Ctrl+T

Swap the characters before and after the caret.

Ctrl+Shift+T

Swap the words before and after the caret.

Shift+Alt+T

Swap the current line with the next line.

Alt+Up

Move the selected lines up.

Alt+Down

Move the selected lines down.

Movement

Down

Move the caret one line down.

Up

Move the caret one line up.

Left

Move the caret to the previous character.

Right

Move the caret to the next character.

Ctrl+Left

Move the caret to the previous word.

Ctrl+Right

Move the caret to the next word.

Home

Move the caret to the start of the current line.

End

Move the caret to the end of the current line.

Ctrl+Home

Move the caret to the start of the script.

Ctrl+End

Move the caret to the end of the script.

Page Up

Move the caret one page up.

Page Down

Move the caret one page down.

Ctrl+Page Up

Move the caret to the topmost visible line.

Ctrl+Page Down

Move the caret to the bottommost visible line.

Scroll

Ctrl+Down

Scroll down by one line.

Ctrl+Up

Scroll up by one line.

Selection

Ctrl+Num-

Expand the current selection semantically.

Ctrl+Num+

Shrink the current selection semantically.

Escape

Clear the selection.

Shift+Down

Move the caret one line down and expand the selection.

Shift+Up

Move the caret one line up and expand the selection.

Shift+Left

Move the caret to the previous character and expand the selection.

Shift+Right

Move the caret to the next character and expand the selection.

Ctrl+Shift+Left

Move the caret to the previous word and expand the selection.

Ctrl+Shift+Right

Move the caret to the next word and expand the selection.

Shift+Home

Move the caret to the start of the current line and expand the selection.

Shift+End

Move the caret to the end of the current line and expand the selection.

Ctrl+Shift+Home

Move the caret to the start of the script and expand the selection.

Ctrl+Shift+End

Move the caret to the end of the script and expand the selection.

Shift+Page Up

Move the caret one page up and expand the selection.

Shift+Page Down

Move the caret one page down and expand the selection.

Ctrl+Shift+Page Up

Move the caret to the topmost visible line and expand the selection.

Ctrl+Shift+Page Down

Move the caret to the bottommost visible line and expand the selection.

Ctrl+A

Expand the selection to the whole script.

Ctrl+Shift+W

Select the word at the caret.

Shift+Alt+Down

Expand the block selection downwards.

Shift+Alt+Up

Expand the block selection upwards.

Shift+Alt+Left

Expand the block selection to the left.

Shift+Alt+Right

Expand the block selection to the right.

Ctrl+Shift+Alt+Left

Expand the block selection to the previous word.

Ctrl+Shift+Alt+Right

Expand the block selection to the next word.

Message List

The Message List tool shows the result of the most recent validation cycle for the current project as well as the messages that have been generated by the Browser Tool and the Inspector Tool.

This tool can be activated with the Alt+H+M keyboard chord.

tool message list
Figure 5. Workshop Application - Message List

Validation is performed in the background while editing the scripts of the current project. The message list is updated automatically according to the results that are collected asynchronously. There is no dedicated Build or Compile action that must be performed.

When a project is opened, an initial validation cycle is performed (which may include read-only access to the filesystem), so it is perfectly normal if messages appear right away.

The messages are shown in a tabular list, where each row represents a single message and the columns have the following meaning:

  1. The message severity (see below).

  2. The message source, which will be the script filename or Browser / Inspector, if the message has been generated by the Browser Tool / Inspector Tool.

  3. The source code location in row:column notation or n/a if not available.

  4. The message text.

These are the message severities:

icon small error Error

An error usually indicates a problem in the script code, for example a syntax or semantic error.

icon small warning Warning

A warning usually indicates a problem that will occur when inspecting, browsing or processing script members, for example non-existent files or directories.

icon small info Info

An info is a purely supporting notice, which may be ignored without causing any problems.

The messages in the list are sorted by severity (error first, info last), source, location (row, then column) and text.

The following toolbar commands are available in the tool window:

Table 8. Message List commands

icon show errors

Toggle Errors
Shows or hides error messages.

icon browser

Toggle Browser
Include Browser Tool messages?

icon show warnings

Toggle Warnings
Shows or hides warning messages.

icon inspector

Toggle Inspector
Include Inspector Tool messages?

icon show infos

Toggle infos
Shows or hides info messages.

icon script

Choose Script
Chooses which script messages to include.

These actions are available from the Message List  Context Menu (open with right-click), for the message under the cursor:

Table 9. Message List context menu

icon jump to code

Jump to Code
Opens the referenced script and jumps to the location in the script code.

F3

Double-click a message in the list to trigger the Message List  Context Menu  Jump to Code action.

The buttons for filtering messages by their severity are labeled
[ icon small error n of m Errors ],
[ icon small warning n of m Warnings ],
[ icon small info n of m Infos ],
where n is the number of messages that are shown in the list and m is the total number of messages in the validation result for the current project. If n is equal to m, the buttons are labeled
[ icon small error n Errors ],
[ icon small warning n Warnings ],
[ icon small info n Infos ].

Toggle the [ icon small browser Browser ] and [ icon small inspector Inspector ] buttons to show or hide the messages that have been generated by the Browser Tool or the Inspector Tool. These messages have a source value of Browser or Inspector.

Click one of these buttons to choose which script messages to include:

[ icon small script Current ]
Include only those messages that belong to the current script in the Script Editor.

[ icon small script Open ]
Include only those messages that belong to a script that is open in the Script Editor.

[ icon small script All ]
Include all script messages in the validation result.

[ icon small script None ]
Exclude all script messages in the validation result.

Type Explorer

The Type Explorer tool shows the ConfigType instances that are available for use in the Script Editor.

This tool can be activated with the Alt+H+T keyboard chord.

tool type explorer
Figure 6. Workshop Application - Type Explorer

The following toolbar commands are available in the tool window:

Table 10. Type Explorer commands

icon collapse all

Collapse All
Collapses all nodes of the type tree.

icon expand all

Expand All
Expands all nodes of the type tree.

icon project explorer

Show By Name
Uses the full name of each type to build a name tree, for example Tinman / App.

icon show classes

Show Classes?
Only show types in the tree that are classes?

icon show sorted

Show Alphabetically
Uses the last name part of each type to build a list, for example Widget.

icon show structs

Show Structs?
Only show types in the tree that are structs?

icon show type

Show By Type
Uses the inheritance hierarchy to build a type tree, for example App / Widget.

icon show enums

Show Enums?
Only show types in the tree that are enums?

icon find

Find
Filters the tree by showing only those nodes that contain the search phrase in their title.

These actions are available from the Type Explorer  Context Menu (open with right-click), for the message under the cursor:

Table 11. Type Explorer context menu

icon help browser

Show Help
Shows the documentation of the selected type in the Help Browser.

F1

Double-click a type in the tree to trigger the Type Explorer  Context Menu  Show Help action.

Help Browser

The Help Browser tool shows the documentation of a ConfigType.

This tool can be activated with the Alt+H+H keyboard chord.

Using the Context Menu  Show Help action or the global F1 hotkey will show the Help Browser for the current context.

tool help browser
Figure 7. Workshop Application - Help Browser

The full name of the current type is shown in the toolbar (for example: Tinman.Cubemap.Rect). Its documentation is shown in the content area of the Help Browser tool.

Developer info

The documentation content is generated by processing the TypeDocNode object of the config type with a custom IConfigDocNodeVisitor object, which outputs a WPF-specific document model.

The Processor Tool uses another visitor to generate the ASCII content to show on the console.

The following toolbar commands are available in the tool window:

Table 12. Help Browser commands

icon back

Back
Navigates back in the page history.

icon forward

Forward
Navigates forward in the page history.

icon jump member

Jump To
Jumps to a member of the config type.

icon jump history

Recent Pages
Jumps to a recently visited page.

Inspector Tool

The Inspector tool shows the hierarchical data structure of a ConfigValue.

It can be activated with the Alt+H+I keyboard chord.

tool inspector
Figure 8. Workshop Application - Inspector Tool

(1) The origin of the inspected value, either script / member or file path
(2) The type of the inspected value
(3) The field name of a ClassType
(4) The field value of a ClassType
(5) The script source of the selected field

To open the context menu for the inspected value, right-click on the caption bar (1). To close the inspected value, press Escape or use the context menu.

The native object graph that has been created for the inspected value usually holds system resources, such as open files. Closing the inspected value will free those resources.

A field name (3) may have a prefix symbol, which indicates the following:

  1. Dot (·)
    The field is virtual, its value is based on a native object.

  2. Circle ()
    The actual value is equal to the default field value.

  3. Bullet ()
    The actual value differs from the default field value.

By clicking (3) or (4), individual fields in the hierarchy of the inspected value may be selected.

To open the context menu for the selected field, right-click on the field name (3).

The script source of the selected field is shown in (5).

The shown script code may be copied into the Script Editor, for example to create new script members.
Developer info

When inspecting a value, the registered ConfigValueBrowser objects are asked in turn to provide an inspection result, by calling the Inspect method.

Plug-ins may provide own ConfigValueBrowser objects, thus providing new inspection methods.

This is the default logic for inspecting a given input value:

  1. If value is a file path, wrap it in a Path.

  2. If value is a native IConfigurable object, convert it to an Obj.

  3. If value is a Path:

    1. Existing file with case-insensitive suffix .hgt?
      Wrap as Heightmap.Dataset and inspect the resulting native IHeightmap object.

    2. Existing file with case-insensitive suffix .pyr?
      Wrap as Pyramid.Dataset and inspect the resulting native IPixelPyramid object.

    3. Try to wrap as a Model.Read; on success, inspect the resulting native IModelReader object.

    4. Try to wrap as a Shape.File; on success, inspect the resulting native IShape object.

    5. Try to wrap as a Image.File; on success, inspect the resulting native IImage object.

    6. Existing file with case-insensitive suffix .mbtiles?
      Wrap as MBTiles and inspect the resulting IPixelPyramid object.

  4. If value is a ConfigValue, inspect its hierarchical data structure.

These actions are available from the Inspector Tool  Context Menu (open with right-click):

Table 13. Inspector Tool context menu

icon help browser

Show Help
Shows the documentation of the selected item in the Help Browser.

F1

icon project explorer

Find in Project
Shows the model node of the selected item in the Project Explorer.

F2

icon jump to code

Jump to Code
Shows the source code of the selected item in the Script Editor.

F3

icon browser

Show in Browser
Evaluates the selected item and shows it in the Browser Tool.

F5

icon import from file

Import from file
Imports a file and inspects the resulting value.

F8

icon jump to filesystem

Jump to filesystem
Opens the folder that contains the selected path value.

F9

icon close

Close
Closes the inspected value.

Browser Tool

The Browser tool visualizes a ConfigValue by creating and running an embedded application for it.

It can be activated with the Alt+H+B keyboard chord.

tool browser
Figure 9. Workshop Application - Browser Tool

The caption bar shows the origin of the browsed value, which is either the script / member name or the file path.

To open the context menu for the browsed value, right-click on the caption bar. To close the browsed value, press Escape or use the context menu.

The native object graph that has been created for the browsed value usually holds system resources, such as open files. Closing the browsed value will free those resources.

The client area runs an application that wraps the browsed value.

For details on how to use the embedded applications, please refer to the content of the help browser in the Demo Application:

Table 14. Built-in browser applications
Documentation Config API Native API

Canvas 2D

CanvasView

CanvasWidget

Map 2D

n/a

MapViewWidget

Model 3D

ModelView

ModelWidget

Scene 3D

n/a

SceneViewWidget

Terrain 3D

TerrainView

TerrainViewWidget

Test

Widget.Test

TestWidget

Texture

n/a

TextureWidget

Developer info

When browsing a value, the registered ConfigValueBrowser objects are asked in turn to provide a browser application, by calling the Browse method.

Plug-ins may provide own ConfigValueBrowser objects, thus providing new browsers.

This is the default logic for browsing a given input value:

  1. If value is an Image, wrap it in a Heightmap.Dataset.

  2. If value is a Shape, wrap it in a Pyramid.MapShapes.

  3. If value is a Heightmap or Pyramid, wrap it in a CanvasView.

  4. If value is a Model, wrap it in a ModelView.

  5. If value is a Tinman.Widget, wrap it in an App.Widget.

  6. If value if an App, run the resulting native IApplication object in the client area.

  7. If value is a file path, wrap it in a Path.

  8. If value is a Path:

    1. Existing file with case-insensitive suffix .hgt?
      Wrap as Heightmap.Dataset and browse the resulting value.

    2. Existing file with case-insensitive suffix .pyr?
      Wrap as Pyramid.Dataset and browse the resulting value..

    3. Try to wrap as a Model.Read; on success, browse the resulting value.

    4. Try to wrap as a Shape.File; on success, browse the resulting value.

    5. Try to wrap as a Image.File; on success, browse the resulting value.

    6. Existing file with case-insensitive suffix .mbtiles?
      Wrap as MBTiles and browse the resulting value.

These actions are available from the Browser Tool  Context Menu (open with right-click):

Table 15. Browser Tool context menu

icon help browser

Show Help
Shows the documentation of the browsed value in the Help Browser.

F1

icon project explorer

Find in Project
Shows the model node of the browsed value in the Project Explorer.

F2

icon jump to code

Jump to Code
Shows the source code of the browsed value in the Script Editor.

F3

icon inspector

Send to Inspector
Sends the browsed value to the Inspector Tool.

F4

icon import from file

Import from file
Imports a file and browses the resulting value.

F8

icon jump to filesystem

Jump to filesystem
Opens the folder that contains the browsed path value.

F9

icon close

Close
Closes the browsed value.

Processor Tool

The Processor Tool processes takes a ConfigValue of type Operation, creates a native operation for it and runs it in the background. A processor job item is displayed for each operation.

It can be activated with the Alt+H+R keyboard chord.

tool processor
Figure 10. Workshop Application - Processor Tool

The following toolbar commands are available in the tool window:

Table 16. Processor Tool commands

icon ball.blue

Show running operations?
Toggles job items that are still running.

icon ball green

Show finished operations?
Toggles job items that have succeeded.

icon ball yellow

Show cancelled operations?
Toggles job items that have been cancelled.

icon ball red

Show failed operations?
Toggles job items that have failed.

Action  Close all
Closes all job items that are not running.

Action  Close all failed
Closes all job items that have failed.

Action  Close all cancelled
Closes all job items that have been cancelled.

Action  Close all finished
Closes all job items that have suceeded.

Action  Cancel all running
Cancels all running processor jobs.

Each processor job has a corresponding item in the vertical job list.

To open a popup window with additional information about a processor job, left-click its item in the job list. In the popup window, you may choose to cancel resp. close the processor job.

The circle shape on the left indicates the job status:

  • Blue
    The job is running and its progress (e.g. 50%) is displayed in the shape.

  • Green
    The job has finished successfully and OK is displayed in the shape.

  • Yellow
    The job has been cancelled and ^C is displayed in the shape.

  • Red
    The job has failed with an error and <!> is displayed in the shape.

The lines of the center text have the following meaning:

  1. Name of the script that contains the job.

  2. Name of the member that represents the job.

  3. The concrete Operation type of the job.

On the right, the RT and ETA values show the total running time resp. the estimated time to completion of the processor job.

These actions are available from the Processor Tool  Job Item  Context Menu (open with right-click):

Table 17. Processor Tool context menu

icon help browser

Show Help
Shows the documentation of the processed Operation type in the Help Browser.

icon project explorer

Find in Project
Shows the model node of the processed Operation value in the Project Explorer.

icon jump to code

Jump to Code
Shows the source code of the processed Operation value in the Script Editor.

icon inspector

Send to Inspector
Sends the processed Operation value to the Inspector Tool.

job cancel

Cancel
Cancels the running processor job.

icon close

Close
Closes the processor job.

Dialog Windows

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

Dialog windows can have interactive content. In this case, clickable links are included in the content, which will trigger an action, as indicated by the link text.

Licence Key

The licence key dialog is shown on startup when no valid licence key has been found in any of these places:

dialog licence key
Figure 11. Workshop Application - Licence Key Dialog

Continue with Ok to use the selected licence key or quit with Cancel.

You can click the links on the dialog content to perform various actions:

licence metadata

This will take you to the Licencing and Pricing page.

tinman_3d.licence-request.user.id-01234567.json.text

Opens the licence request file that has been generated in the current user’s home directory, for the shown USER and DOMAIN metadata.

Click here to visit the order page for a 3 months User licence key

Opens the order page for a 3-months User licence and fills in the licence metadata fields, for the shown shown USER and DOMAIN metadata.

After a purchase, licence keys are delivered instantly, so you can keep the dialog open and paste the delivered licence key right away.

Click here to paste a licence key from the clipboard

Selects the licence key that is currently stored in the system clipboard.

Click here to use the free evaluation license

File Import

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

dialog file import
Figure 12. Workshop Application - File Import

Use Yes to import the file using the selected method or No to cancel the file import.

Additional non-default file formats for raster images, vector data and 3D models may be available. Please refer to the system information in the About Box for details.

Use the links in the dialog content to choose how to import the file:

none

Do not import the file. This has the same effect as choosing No.

path

The file path will be imported as a path value. If possible, the path will be relative to the target script file.

Image:FORMAT

The file will be imported as an Image.File value, using the indicated format.

Shape:FORMAT

The file will be imported as a Shape.File value, using the indicated format.

Model:FORMAT

The file will be imported as a Model.Read value, using the indicated format.

Heightmap

The file will be imported as a Heightmap.Dataset value.

Unsaved Changes

If you close a script, project or the Workshop, you will be prompted if there are any unsaved file changes. When the dialog opens, all unsaved file changes are marked as: will be saved.

dialog save all
Figure 13. Workshop Dialog - Unsaved Changes (save all)

Click on Discard All to mark all unsaved file changes as: will be discarded:

dialog save none
Figure 14. Workshop Dialog - Unsaved Changes (discard all)

Use the individual file links to toggle between will be saved and will be discarded:

dialog save some
Figure 15. Workshop Dialog - Unsaved Changes (save / discard some)

Use Ok to save / discard changes as selected and to continue with the provoking action.

Use Cancel to cancel the provoking action and retain all unsaved changes.

Conflicting Changes

If modifying script files both in the Workshop and in another editor, conflicting changes may occur. In this case this dialog will be displayed. When the dialog opens, all conflicting changes are marked as: will be applied.

dialog apply all
Figure 16. Workshop Dialog - Conflicting Changes (apply all)

Click on Ignore All to mark all conflicting changes as: will be ignored:

dialog apply none
Figure 17. Workshop Dialog - Conflicting Changes (ignoring all)

Use the individual file links to toggle between will be applied and will be ignored:

dialog apply some
Figure 18. Workshop Dialog - Conflicting Changes (apply / ignoring some)

To apply an external change, the script file is reloaded, which discards the modifications in the Script Editor.

To ignore an external change, the script file is saved, which overwrites the external change with the modifications in the Script Editor.

Use Ok to apply the selected actions.

Error Report

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

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

dialog error report
Figure 19. Workshop Application - Error Report

Use Ok to dismiss the error report.

You can click the links on the dialog content to perform various actions:

show more

Show additional error details.

show less

Show error message only.

license

This will take you to the Licencing and Pricing page.

Developer info

The displayed error information is based on TinmanError and ValidateResult.

About Box

The about box shows a system information report.

The about box can be used to quickly determine where to find the application settings file and which 3rd-party libraries and plugins have been detected.

You can reach the about box from the application menu in the main toolbar.

dialog about box
Figure 20. Workshop Application - About Box
Developer info

The content of the system information report is generated with TinmanModule.SystemInfo.

The system information report contains several items that are relevant to the Workshop:

Relevant parts of system information report
...

Tinman.Terrain v1.0 - 2022/04/16

  ...

  ImageFormat (1)

    'Any' : Automatic image format
    'BMP' : Built-in support for BMP
    'DDS' : Built-in support for DDS
    'GIF' : Built-in support for GIF
    '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 3.0.4, released 2020/01/28
    'GDAL+PROJ' : GDAL 3.0.4, released 2020/01/28

  ShapeFormat (2)

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

...

Tinman.Engine v1.0 - 2022/04/16

  ...

  ModelFormat (3)

    'Any' : Automatic model format
    'CMH' : Tinman 3D Compiled Model Hierarchy
    'LAS' : LASer (LAS) File Format 1.3
    'OBJ' : Wavefront OBJ
    'ASSIMP5' : Open Asset Import Library 5.2

Tinman.AddOns v1.0 - 2022/04/16

  ...

  ConfigValueBrowser: (4)

    'Tinman/AddOns'
    'Tinman/AddOns/SQLite'

...

Tinman.Workshop v1.0 - 2022/04/16

  Settings : c:\Users\...\AppData\Local\...\Tinman.Workshop (5)

  GeoRegistry : EPSG 9.9.1 / Tinman 1.0 (6)
1 The available raster image formats
2 The available vector shape formats
3 The available 3D model formats
4 The value browsers that are available to the Browser Tool
5 The path to the directory where the Workshop stores additional files.
6 The content version of the embedded geo registry.
Developer info

Plug-ins may provide additional raster image, vector shape and 3D model formats as well as new config type and value browsers.

The geo registry file is loaded with GeoRegistry.Load.

data/epsg-9.9.1.dat

The same file is embedded in the Geodata Processor.

The Workshop stores additional files in its Settings directory:

licence-key.txt

This is a text file that contains the licence key of the user. This file is written when the user provides a new key via the Licence Key dialog window.

Settings.json

This is a JSON file that stores user-specific application settings.

The following settings may be edited manually:

Workshop settings file
{
"CodeFontFamily": "Consolas", (1)
"CodeFontSize": 14, (2)
"LastProjectFilePath": "<some-path>\\geodata_examples.twp", (3)
"ActiveScriptFile": "bluemarble2.tms", (4)
"OpenScriptFiles": ["bluemarble2.tms", "egm96.tms"], (5)
"DockSiteLayout": "..."
}
1 Name of the font to use in the Script Editor
2 Size of the font in the Script Editor
3 Path to the project file that will be loaded on startup
4 Name of the project script to select in the Script Editor on startup
5 Name of the project scripts to open in the Script Editor on startup
These settings will be read on startup and written on shutdown, so any manual editing should take place before the Workshop is started.

Command-line

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

Developer info

The command-line log levels map to LogVerbosity. Logging is configured with LoggingUtil.BasicConfiguration.

The console window is opened with Terminal.Window.

The LicenceDomain.AllowUnlockByEnvironment attribute of LicenceDomain.Tinman is set to false when the no-env token is present.

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.

Plug-ins

Developer info

This section contains technical information for developers.

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

tinman3d_workshop.plugin.*.dll
tinman3d_workshop.plugin.*.exe

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

  • It must be a .NET Framework 4.8 assembly or .NET Standard 2.0 assembly.

  • It must use the same Tinman assembly versions as the hosting Workshop (see About Box).

  • It must define a subclass of TinmanModule (please refer to the AddOns source code for examples).

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