1. Language selection drop-down
2. Project options
3. Project file path
4. Folder navigation
## Loading Models
To load a valid model, either click it in the list or enter a **file path** and click the **Stream** button in the lower-right corner.
Below is a list of the available interactive icons and their functions.
| Button | Action |
|---|---|
|
| Shows the list of log files. You can open a log file and copy its contents to the clipboard. |
|
| The local model is invalid and can no longer be accessed. |
|
| This local version is outdated and can no longer be accessed. You can set the expiration date of a model during model generation in **UDiTH Builder**. |
|
| Streams a model from the internet. |
|
| Downloads a model to the local device, for example when taking a mobile device to a plant without an internet connection. |
|
| Opens the camera to scan a QR code. |
|
| Copies the file name to the input box. |
|
| Deletes the local version. |
> Please use UDiTH Webservices if you want to protect UDiTH models. Since UDiTH 7, Basic Authentication is no longer supported.
You can also **allow downloads** using the options provided in the **Generate output** settings of **UDiTH Builder**.
### Close Window
> If you click **Close** in the top-right corner or press **Alt + F4**, a confirmation message will appear to help prevent accidental closure of the program or loss of data.
---
# UDiTH App — Multi-Window System
# Multi-Window System
The tabs within **UDiTH** can be customised using drag and drop. The **Search**, **Files**, **Attributes**, and many other tabs can be repositioned easily by clicking and dragging them across the screen. The image below shows two possible layout options after moving a tab to a new position.
> This option must be activated by an administrator.
---
# UDiTH App — Navigation
# Navigation
On touch devices, you can navigate like this:
### Two-finger parallel drag: pan
Place two fingers on the 3D view and move them in approximately the same direction. The camera pans by the average movement of both fingers.
Recognition requires both fingers to move more than 10 screen units and the angle between their movement vectors to be less than 90 degrees. When **Swap pan and rotate** is enabled, this gesture rotates instead.
### Pinch or spread: zoom
Move two fingers toward or away from each other to zoom around their midpoint.
- The gesture is recognized after the distance between the fingers changes by more than 20 screen units.
- The fingers must move in substantially opposing directions: the angle between their movement vectors must be greater than 90 degrees.
- Spreading and pinching produce opposite zoom directions.
- Zoom distance is normalized for display DPI.
If a two-finger movement does not satisfy either the pan or pinch thresholds, no navigation gesture starts. A gesture is classified once and keeps that mode until it ends; lift both fingers before switching from pan to pinch or vice versa.
### Tap: select
A tap on a selectable model object selects it exclusively. A tap on empty model space clears the selection. If multi-selection mode is already active, a tap toggles the touched object instead.
### Press and hold: add or remove from selection
On a device currently operating in touch-input mode, hold a finger on a selectable object for **0.75 seconds**. The touched object is toggled in the current selection. Moving into a drag or lifting before the threshold cancels the pending hold action.
### Double-tap: contextual model action
A double-tap is recognized from the platform tap count or from two taps occurring within approximately 0.3 seconds. In a focused 3D view it can:
- fit the camera to the selected object when that object permits move-to-on-double-click;
- enter the nearest visible projection sphere when a laser-scan element is selected;
- begin editing a selected comment;
- restart line tracking from the selected object while line tracking is active.
The applicable subsystem decides the result. Double-tap therefore has no effect when the selection or current mode does not support one of these actions.
### Window Zoom: one-finger rectangle
When **Window Zoom** is enabled, a one-finger drag draws a rectangular overlay instead of orbiting. Release the finger to zoom the 3D camera to that rectangle. An empty rectangle is ignored.
## Walk mode
Walk mode treats the centroid of up to three active touches as a floating joystick. The joystick appears after the touch centroid leaves a DPI-scaled dead zone. The number of fingers present when the gesture begins selects the joystick function.
| Fingers | Horizontal drag | Vertical drag |
| --- | --- | --- |
| One | Turn left/right | Move forward/backward |
| Two | Strafe left/right | Elevate down/up |
| Three | Turn left/right | Look vertically |
The joystick center is reset whenever fingers are added or removed. Lift all fingers to hide it. A pinch can also change the camera distance from a focused avatar, constrained by the walk camera's minimum and maximum distance.
## PDF documents
PDF gestures are active only while the PDF view owns the interaction and no PDF markup tool is active.
- **One-finger drag:** pans the page.
- **Two-finger parallel drag:** also pans the page.
- **Pinch or spread:** zooms around the midpoint of the fingers.
- **Window Zoom enabled:** one-finger drag draws a zoom rectangle; pinch zoom is disabled while this mode is enabled.
The PDF controller can optionally restrict zoom to positions inside the page. Releasing the final touch ends the PDF interaction and commits any post-gesture update.
## IntelliPID and other 2D drawing views
- **Two-finger parallel drag:** pans an IntelliPID view while the pointer is over it.
- **One-finger drag:** pans when the view's Pan tool is active.
- **Pinch or spread:** changes the orthographic zoom around the gesture midpoint, subject to the view's zoom limits.
- **Pinch or spread on a directional drawing image:** scales the image around the gesture midpoint when the image uses the `DirectionalZoom` component.
Touching with more than one finger suppresses ordinary IntelliPID element highlighting so navigation is not mistaken for element selection.
## UI gestures
### Tap
A tap is processed as the primary pointer action. It activates buttons, tabs, tree nodes, menu items, links, toggles, and similar controls. Tapping a text field focuses it and, on mobile or browser-streamed touch clients, can open the on-screen keyboard.
### Drag to scroll
Touch-dragging scrolls supported lists and toolbars. The main left-menu toolbars install explicit vertical drag-scrolling; standard Unity scroll views may also provide their normal touch scrolling.
For browser-streamed touch input, scrolling begins when the finger moves more than 5 panel units along the scroll view's permitted axis within 1 second. This threshold leaves room for a tap or long-press to be recognized.
### Streamed long-press: context menu
In the browser-streamed client, hold one finger on the same UI element for more than **1 second**, moving no farther than 5 panel units. On release, the element's context menu opens if that element exposes one. Scrolling, leaving the original element, or using more than one finger cancels the action.
This streamed UI long-press is separate from the native 0.75-second model-selection hold.
### Direct manipulation
Draggable controls continue to use pointer drag behavior on touch. Examples include movable tabs, splitters, sliders, and application-specific drag-and-drop targets. The exact result belongs to the touched control rather than to a global multi-touch gesture.
---
# UDiTH App — Camera
# Camera
**UDiTH** offers three camera modes. After loading a new model, **UDiTH** starts in Orbit mode by default.
You can select another mode by clicking the 
**Select camera mode** icon in the top-left corner of the screen.
| Mode | Hold left mouse button | Hold right mouse button | Mouse wheel | Keyboard | |
|---|---|---|---|---|---|
|
| Orbit mode | Rotate the camera around the centred object | Move the camera forwards or backwards | Move the camera towards or away from the mouse pointer | W, A, S, D or the arrow keys: move camera Shift + W, Shift + S: raise or lower camera Space: raise camera |
| Flight mode | Rotate the camera | Move the camera forwards or backwards | Move the camera towards or away from the mouse pointer | W, A, S, D or the arrow keys: move camera Shift + W, Shift + S: raise or lower camera Space: raise camera |
| Walk mode | Rotate the camera left or right, and move forwards or backwards | Two fingers: move the camera left or right, and up or down | Three fingers or press and hold the mouse wheel: rotate the camera |
| Toggle display of 360° panorama centres A light background indicates that this option is active. Panorama locations then appear as red spheres in the model. To deactivate it, click the button again. |
| Toggle orthographic camera mode To deactivate this function, move the camera or click the button again. |
| Reset view Clicking this icon resets all options, such as camera type, position, highlighting, and more. Everything is restored to its default state. |
| Set near/far clipping plane Sets the distance from the camera at which objects are rendered. For example, if the far clipping plane is set to 100 metres, objects beyond that distance are not rendered. |
| Set camera position Places the camera at the specified position, facing the given target. |
| Go to GPS position Places the camera at the specified GPS location. This function requires an active GPS device. |
| Follow GPS position This function follows the live GPS signal and requires an active GPS device. |
| Action | Alternative action | | | | | 2D |
|---|---|---|---|---|---|---|
| Touch one-finger click | Select object | ||||
| Touch one-finger double-click | Jump to the closest panorama or markup | ||||
| Move forward/zoom in | |||||
| ↑ | W | |||||
| Move backwards / zoom out | |||||
| ↓ | S | |||||
| Shift-↑ | Shift-W | Move up | ||||
| Shift-↓ | Shift-S | Move down | ||||
| ← | A | Move left | Rotate left | |||
| → | D | Move right | Rotate right | |||
 -↑
| Swipe | Orbit up | Rotate up | Move forward | ||
|
-↓
| Swipe | Orbit down | Rotate down | Move backward | ||
|
-←
| Swipe | Orbit left | Rotate left | |||
|
-→
| Swipe | Orbit right | Rotate right | |||
| MMB-Press&Drag-↑ | Pan/scroll up | Rotate up | ||||
| MMB-Press&Drag-↓ | Pan/scroll down | Rotate down | ||||
| MMB-Press&Drag-← | Pan/scroll left | Rotate left | ||||
| MMB-Press&Drag-→ | Pan/scroll right | Rotate right | ||||
| Toggle Pan Mode activates the panning feature. Alternatively, you can hold down the middle mouse button, press and hold the mouse wheel, or press the left and right mouse buttons simultaneously. On mobile devices, simply swipe the screen with two fingers to pan. |
| When you click one of the spheres, the camera moves to its centre and overlays the model with the panorama image captured at that position. While inside a panorama sphere, you can only rotate the camera. You can zoom in and out using the mouse wheel, or by pinching and spreading on mobile devices. |
|
You can select the most recently activated panoramas in chronological order from the drop-down list. Selecting one moves the view to that specific sphere. |
| The Opacity slider adjusts the transparency of the overlaid panorama image, allowing you to increase or decrease its visibility. | |
|
To exit panorama mode, click the Toggle display of 360° panorama centres button [] again.
|
|
Click the Settings button [ ] on the left side of the screen to access the quick navigation controls in the lower-right corner of the screen, regardless of the camera mode. Scroll down to 3D user interface and toggle Minimap.
|
|
You can then move the camera using the left mouse button and rotate it using the right mouse button, directing it precisely to a point on the map with a left or right click. The 90° angle shown indicates the camera's field of view. |
| You can zoom in and out using the magnifying glass icons. | |
| You can use the bar on the right to change the camera's height. The lower half represents the total height of the model. |
|
Click the Settings button [] on the left side of the screen to access the quick navigation controls in the lower-right corner of the screen, regardless of the camera mode. Scroll down to 3D user interface and toggle Common views cube.
|
| The cube in the upper-right corner of the screen indicates direction: N - North, W - West, S - South, E - East, U - Up, D - Down. |
| Clicking any face of the cube, or the small spheres connecting two or three faces, orients the camera to look directly at that face or corner. For example, clicking Up directs the camera to point straight down. | |
| In the Settings menu, you can toggle the visibility of the cube, switch between compass and XYZ modes, and make other adjustments. |
### Common Attribute Display during Multi-Selection
To view common attributes for multiple objects, either hold down the **Ctrl** key while selecting them or click predefined groups or plant sections. This feature allows the simultaneous display of shared standard and custom attributes for up to 1,000 objects.
## Select Clipping Mode
| **Select clipping mode** To improve object visibility, clip the view to exclude the area around the selected objects. |
| **Volume clipping** Select an object and surround it with a rectangular clipping box that matches its size. This ensures that only fully enclosed objects remain visible. |
| **Customise clipping** To change the dimensions of the clipping box, move the slider between 0 and 25 metres or drag one side of the box directly. To reposition the box, drag the coloured arrows. |
| **Centre and fit selected objects** This option automatically adjusts the view if the size of the clipped volume changes. |
| **Save volume to clipboard** Saves the volume of the current clipping to the clipboard so that you can paste it into an Excel file. |
| In **IntelliClipping**, the original clipping box follows the shape of the selected object itself, which is surrounded by the default selection box. |
| **Inverse clipping** provides a clear view towards the centre of the selected objects by clearing one quadrant along the x, y, and z axes. All other quadrants remain visible as usual. |
| **Show/hide grid planes** You can add a grid that responds to the camera's distance from the object. The grid is displayed as 1 m x 1 m, 10 m x 10 m, or 100 m x 100 m depending on the camera's distance from the object. To change the size of the grid, drag the sides of the quadrant. |
|
| **Save volume to clipboard** Saves the volume of the current clipping to the clipboard so that you can paste it into an Excel file. |
| min Y | min X | min Z | max Y | max X | max Z | |
|---|---|---|---|---|---|---|
| NewVolume | 3023.2Z | 2375.12 | 67.19 | 3037.21 | 2393.12 | 72.15 |
|
| **Centre and fit selected objects** Select the objects you want to centre in the window and then click this button. If nothing is selected, all elements are fitted into the window. |
| **Toggle selected objects visibility** To hide or show objects, select them and click this button. |
| **Show only selected objects** This function hides all objects except the selected ones. Toggle it to activate or deactivate the filter. |
| **Highlight selected objects** All objects except the selected ones appear greyed out and semi-transparent. Toggle the button again to deactivate this function. |
 | **Colourise selected objects** Change the display colour of selected objects by opening the colour menu. |
|---|
#### Colour Options
 | **Advanced colour selection** opens a pop-up menu for detailed colour selection, allowing you to choose from the full RGB colour spectrum: |
|---|
|
Once you have chosen the required colour, confirm [ ] or cancel [ ] your selection.
The selected object or objects are displayed immediately in the chosen colour.
|
 | **Pick colours** lets you take a colour from a 3D object and save it under **Custom colours** so that you can use it again later. Activate the function, click an object to pick its colour, and then select a white custom colour square to save it. |
|---|---|
 | **Clear style** resets the colour of the selected objects to their default colour, which was initially assigned during the building process. |
 | **Reset all colours** restores **all** assigned colours for **all** objects to the default colours set during the building process. |
|
Your model is loaded with a default colour file. You can also create a **Custom colour file** and load it via the file management menu. |
| Colour | Condition |
|---|---|
| red | Task=Equipment |
| blue | Task=Structure |
| \#FF00FF22 | Task=Supports |
| red | Task=Cableway |
| red | Task=Conduit |
| red | Task=HVAC |
| \#FF00FF | piping |
| **Measure distances** creates markers that can be placed on the outlines and corners of 3D objects. The markers can be repositioned by dragging them. |
| **Create new distance measurement** creates two connected markers and displays the distance between them, including the distances in the XYZ planes. |
| **Create new minimum distance measurement** creates two connected markers and displays the minimum distance between two selected objects. |
| **Create new coordinate measurement** creates a single measurement marker together with its coordinate information. |
  
| **Prevent East-Axis/North-Axis/Up-Axis movement** |
| **Ignore intelligent targetting** is explained in more detail in the examples below. |
| This button **Estimates the diameter** of cylindrical objects, such as pipes. This feature is especially useful for laser scans and also displays a red diameter as a visual aid. |
### Intelligent Targeting
| **Activated** intelligent targeting | **Deactivated** intelligent targeting |
|---|---|
|
|
| The **Tools** menu contains specialised functions and options for working with your model. |
| **Calculate centre of gravity** |
| **Export centre of gravity data** as an Excel file. |
| **Highlight linked objects** Clicking this icon greys out all objects that do not have a link. Objects in UDiTH can be linked to documents, maintenance manuals, equipment lists, websites, and more. |
| **Toggle automatic labelling** |
] on the left side of the screen.
2. In the menu that appears in the bottom-right corner of the screen, scroll down to **Attribute options** and click **Select attributes for automatic labelling**.
3. Next, select the required attributes by dragging them into the box on the right:
>
You can type a character on the keyboard to jump directly to that position in the list.
## Activate Line Tracking
| **Activate line tracking** When you select a pipe, the line tracking feature displays arrows at its ends. Clicking these arrows moves directly to the next object in the pipeline. |
> For the best results in **AdapterForSmartReview**, use the following settings under `Tools > Settings > Advanced`: set `Stroking Tolerance` to `100` and enable `Advanced Graphics Handling for measuring and line tracking`.
### QR Decoder
|
| **Open QR decoder** You can place QR codes containing a deep link in your plant so that they can be scanned with a mobile device and interpreted by UDiTH. |
| **Open additonal objects panel** Additional objects help you visualise the size of your model and take a virtual tour. Choose between vehicles and people, then drag the avatars to the required location. |
After placing an avatar, you can move it and rotate it horizontally by dragging the corresponding icons.
You can select an avatar at any time, whether the avatar menu is open or not.
### General Controls
|
| If you select an avatar and enter **Walk mode**, you can walk or drive around using the selected avatar. |
|
| **Delete current object** All avatars that are not saved in a configuration file are lost when the program is closed. |
| **Drop to ground** moves the bottom of the avatar to the nearest surface above or below with a single click. |
| You can **Toggle collision in walk mode**. |
| * To navigate, hold the left mouse button and drag the mouse, or use your finger on a touch device. * To switch to another avatar already placed in the model, click it and continue moving. * You can also use the **W, A, S, D** keys on devices with a keyboard. * To move up, press **Space**. To descend, press **Shift + S**. |
| **Open custom attributes panel** Custom attributes provide a way to add new attributes to a model without having to rebuild the model with the UDiTH Builder. |
> When you use the **Ctrl** key to select multiple objects, their common attributes are displayed directly.
## Custom Attributes Panel
> For details on creating and configuring custom attributes, please refer to the **Custom Attributes** section in **[Custom settings](https://help.caxperts.com/UDiTH%20App/Appendix%20-%20Custom%20settings%20files)**.
In the **Attributes** tab, **Custom attributes** are shown in a distinct colour. In the standard view, they appear in **yellow** and, unlike regular attributes, can be edited. The editing process depends on the type of custom attribute.
- When you select a custom attribute in the **Custom Attributes** panel, the objects are coloured accordingly and the same custom attribute in the **Attributes** tab changes from **yellow** to **red**.
- This can also be achieved by double-clicking a custom attribute. When colouring is applied through the **Custom Attributes** panel, it affects **all** objects. When you double-click a custom attribute instead, objects are coloured according to the **CodeList** colour scheme only when they are clicked in the viewport.
To edit **FreeText** custom attributes, simply type the required value, in the same way as for the **Comment** attribute described earlier. For **CodeList** attributes, a drop-down menu is available from which you can select the required value.
In addition, CodeList-based custom attributes show not only the selected value, but also the colour assigned to that value in the CodeList colour scheme.
### Custom Attribute Tool Bar
 | **Export all changes** This option saves all data entered into custom attributes in a single `.xlsx` file together with the relevant information for the items to which the values are linked. |
|---|---|
 | **Import all changes** This loads previously saved custom attribute values from an `.xlsx` file back into the custom attributes. |
 | **Send email** Custom attribute changes are logged during the session. Clicking this button generates a summary of the changes, copies it to the clipboard, and opens an email in your default email client. The default recipient and subject are configured in the `Meta` tab of `IntelliPIDattributes.xlsx`. For details, see **[Custom settings](https://help.caxperts.com/UDiTH%20App/Appendix%20-%20Custom%20settings%20files)**. |
 | **Show only active** Unused custom attributes do not appear in the list of values or in the legend for the currently displayed **P&ID**. |
 | **Place legend** This function displays a legend on the **P&ID**, showing the corresponding colour keys for custom attributes. The legend can be repositioned by dragging it to any location on the **P&ID**. For details about custom attribute CodeLists and the legend, refer to the description below. |
### Custom Attribute Drop-Down
The drop-down menu allows you to select from custom attributes with CodeList definitions. `None` is the default selection and uses the standard colouring for the **P&ID**. If a custom attribute with a CodeList is selected, objects on the **P&ID** are coloured according to their custom attribute value, and the legend appears below.
## Custom Attributes File
To use **Custom Attributes**, you must create an Excel file containing the required information. This file, named **attributes.xlsx**, must be placed in the model's data folder. The file contains several tabs, as described in the following sections.
### Definition Tab
| Name | Description |
|---|---|
| Id | Identification for custom attributes. |
| Name | The name of the custom attribute as displayed in the UDiTH attributes. |
| SourceAttribute | If the custom attribute is part of an existing attribute, declare the name of the existing attribute here. |
| Filter | See the section Filter. |
| DataType | See the section DataType. |
| DefaultValue | The default value used when the user hasn't made a selection yet. |
| Parameter1-3 | These parameters vary depending on the DataType. See the following sections for details. |
| Name | Description | Parameter1 | Parameter2 | Parameter3 |
|---|---|---|---|---|
| Calculation | Simple predefined calculations. See the section Calculation. | Calculation identifier | - | - |
| CodeList | A drop-down list with differently coloured options. See the section CodeList. | CodeList identifier | Linked CodeList attribute | - |
| FreeText | Any text | Character limit for the text box; use 0 for no limit | - | - |
| Numeric | Any number | Minimum value | Maximum value | Number of decimal places |
**Example**
- `filter1` could not be written in the **Definition** tab, while `filter2` would work.
- The `filter1` attribute is applied to all objects that meet the following criteria: the pipeline attribute starts with `03-LC-1`, is exactly `02-LC-1001`, or is exactly `Pipeline=PR01-LS-2001`.
### CodeList
| The **CodeList** tab contains the details for the DataType `CodeList` used in the **Definition** tab. CodeLists generate drop-down menus in UDiTH for the custom attribute. |
| The **Name** is shown in UDiTH. Each following row without a name belongs to the attribute name specified most recently. For example, after `CS_State`, all values and colours from `B2` to `C6` are part of the `CS_State` attribute. |
| Name | Description |
|---|---|
| TOS | `TOS` (Top Of Steel) returns the elevation in metres at the highest point of the element. |
| BOS | `BOS` (Bottom Of Steel) returns the elevation in metres at the lowest point of the element. |
| ElementColor | Returns the element's current primary colour as a hex code. |
| OriginalColor | Returns the element's original primary colour as a hex code. |
| VisibleColor | Returns the element's visible colour as a hex code, taking temporary UDiTH features into account, for example CodeList colour, highlighting, or centre of gravity. |
| StaticText | Displays the value from `DefaultValue`. |
| Bounds | Returns the bounding coordinates. It uses a format string as `Parameter1` and inserts the values accordingly. The default format is `(%lowX%, %lowY%, %lowZ%) (%centerX%, %centerY%, %centerZ%) (%highX%, %highY%, %highZ%)`. |
| Key | Value |
|---|---|
| Email_To | Preset value used as the recipient when sending a change-set email |
| Email_Subject | Preset value used as the subject when sending a change-set email |
| Workcard_Header | Overrides the work card text header |
| WorkcardMail_To | Like `Email_To`, but for work cards |
| WorkcardMail_Subject | Work card email subject; can use special keywords |
| WorkcardMail_Body | Prefix for the work card email body; can use special keywords |
| Placeholder | Description |
|---|---|
| %workcard% | The `Work` value of the currently selected work card |
| %devicename% | The user's device identifier |
| %date% | Current date |
 
| You can export changes made to custom attributes to an Excel file or import changes made. |
## Email
Changes made to **Custom attributes** during the current session are copied to the clipboard and your email software is opened.
---
# UDiTH App — Project tree
# Project Tree
> The tree bar or tree window remains visible even when you open a PDF, P&ID, or isometric.
Click the **Settings** button. You can then switch between the tree view and the tree bar:
 | **Toggle tree view/tree bar** places the project tree in the menu on the right. |
|---|---|
 | **Tree bar** places the project tree at the top of the main window. You can choose attributes to generate a different project tree automatically. |
 | **Configure project tree**: each attribute defines one level of the project tree. |
---
# UDiTH App — Search tab
# Search Tab
## Search in 3D, Drawings, Documents, and IntelliPID
UDiTH's search function is designed to work across 3D models, 2D drawings, documents, and IntelliPID:
Results are organised by the attributes in which the search string was found. The numbers shown after the attributes indicate the number of matching groups in grey and the affected P&IDs in light blue. When you expand an attribute, the matching groups are displayed as a list, with the corresponding P&ID name highlighted in light blue.
The search function returns two types of result:
| - **Hard results**: These exactly match the entered search criteria and are displayed in white. - **Soft results**: These include variations of the search string, such as characters that are commonly added or omitted when converting data to another format. For example, both `slab 1 0002` and `slab-1-0002` would return results. These are displayed in light grey. |
| Enables or disables automatic camera movement when changing the selected objects. |
|
| **Highlight all objects of the selected category** Objects that do not belong to the selection are greyed out and opaque, while selected objects remain fully coloured. |
|
| **Show only objects of the selected category** Objects that do not belong to the selection are hidden, while selected objects remain visible. |
| **Go to previous/next group** selects the previous or next group of objects in the selected category and focuses the 3D view on those objects. |
| **Go to previous/next part** selects the previous or next part in the selected category and focuses the 3D view on those objects. |
A linked 3D object also includes a link with the name of the P&ID in its attributes. This allows you to switch easily between the P&ID and 3D views for linked objects.
---
# UDiTH App — Files tab
# Files Tab
| Button | Description |
|---|---|
| Adds a new folder. |
|
| Deletes the currently selected tree-object. |
|
| Copy a selected tree-object. |
| Undoes the last change to the tree. |
| Redoes the last undone change to the tree. |
| Saves the currently selected tree object as a .upvtree file. |
| Opens a .upvtree file. |
| Symbol | Description |
|---|---|
|
| **Add** drop-down - Adds a folder object to the model root. Subfolders are not currently supported. Folders can be used to store and group all other file types. For example, if several files belong to one P&ID, you can create a folder containing all relevant files for that P&ID. |
| **2D to 3D projection** |
| **Animation** |
| **AppControl** |
| **Comment** - The comment object contains one comment per node. Comments can be attached to any document element, whether original or sketch-based. Comment objects are always dependencies of the document object. For more details, see **Comment**. |
| **Drawing** |
| **Markup** - The markup file enables you to do markups on your documents, including graphical objects. |
|
| **Measurement** |
| **Package** |
| **Photo** |
| **P&ID sketch** - The sketch file allows you to add sketches to your P&ID, including your custom P&ID symbols. |
|
| **Point of interest** |
| ["*Report*"](./Report) |
| [Screenshot](./Screenshot) |
| [Sketch](./Sketch) |
| [Spraying](./Spraying) |
|
| [View](./View) of the current camera position |
|
| Edit - starts an editing process in a modal manner. |
|
| View - for example, moves the camera to a saved position. |
| Select |
|
| Show or hide item |
 
| Lock or unlock item for modification |
|
| The **file management** menu includes most options for saving and loading, except packages and views, which are available in their respective menus. |
|
| **Save and load configurations** in a `.upv` file. A configuration includes the current settings, clipping, colourisation, view, tags, and more. |
|
| Load a **colour file**. You can choose between local and online colour files. |
| Load a **link file**. You can either replace the existing links or append new ones to them. |
| **Create a link** and copy it to the clipboard. **Example:** `upvapi://http://demo.universalplantviewer.com/demoPlant/4/0/?uid=0003a998-0000-0000-681a-a3ff06552004` |
|
| **Create** a report. |
|
| **Save objects to disk** in OBJ format. |
| **Generate a double-sided ISO PDF**. This will create both an isometric view and an orthographic drawing for better visualisation. |
| Open the **manual**. |
|
| Choose which information to save: |
### Load Configuration File
|
| UDiTH automatically loads a default configuration file. You can save a custom configuration file as `defaultConfig.upv` in the same location as `UDiTH.exe`. |
|
| You can save selected objects as `.obj` files to edit them with a modelling tool or duplicate them in your model. Click **Import avatar from disk** in the **additional objects panel**, then click a location in your model to place the object. After that, you can move and rotate it. |
| These objects are treated as additional objects if you load them in the 3D view. You can delete them in the additional objects panel. If you load them in Sketch mode, they are treated like objects from the catalogue. | ||
| If you save objects as OBJ files, there is a size limit that matches the maximum input size UDiTH can handle. If you export more than 20 objects, the following warning message appears: | |
| Before saving, you can choose to swap the height axis **(Z)** with the breadth axis **(Y)**. | |
> If you do not enter a name for the projection, the name of the selected image will be used.
3. The selected image will be displayed on the right side.
* You can begin placing projection mapping markers on both the 2D image and in the 3D space of your model.
* It is recommended that you position the camera in the 3D space as close as possible to the location from which the image was taken.
* The algorithm that maps the image into the 3D space calculates several possible orientations of the projection sphere. It then chooses the solution closest to the current camera position.
## Mapping a Projection
1. Create a marker and drag it to the correct position in both the 2D and 3D views.
2. Add up to 4 markers to improve accuracy.
3. Move the camera towards the location from which the picture may have been taken to help ensure that the projection is placed correctly.
4. Recalculate the position.
5. If the image is not placed as required, reposition the markers and recalculate until it is placed correctly.
|
| **Adds a selection pin to the 2D mapping view and 3D view** This feature creates colour-coded mapping markers that can be dragged and positioned accurately in both views. You can place up to 4 markers, with at least 3 usually required for reliable mapping. |
| **Removes a selection pin from the 2D mapping view and 3D view** |
| **Changes the focused node** Selecting a marker centres both the 3D and 2D views. The marker colour reflects its focus status and is red by default. |
|
| **Refreshes the projection using the adjusted or pending measurement nodes** |
Pictures are standard 2D images projected into the 3D space. Adjust the **Focal length** setting as required using the control to the right of the mapping buttons. In most cases, the focal length is retrieved automatically from the image metadata.
After the position has been calculated, the camera locks onto the projection sphere and behaves in a similar way to **360° panorama** mode.
 | Leave the projection sphere and use the camera as usual. |
|---|---|
 | Increases opacity of the projected image. |
After the position has been calculated, the camera is locked to the projection sphere. The following button and slider then appear:
|
| Leave the projection sphere and use the camera as usual. |
|
| Increases opacity of the projected image. |
To create a projection of an orthogonal drawing, select **2D** from the breadcrumb menu and then select the required drawing. The drawing opens in a tab. While this tab is active, select **2D to 3D Projection** in the **Files** tab on the right.
 | Select the plane the drawing should be in. |
|---|
|
| Animations are created from sketches. The required buttons are located in the **Files** tab. Once you have created a sketch, you can create an animation while the sketch remains open, which links the two together. |
> Multiple animations can be associated with a single sketch.
## Animation Player
|
| **Edit** opens the animation editor. |
| **Go to first** jumps to the first keyframe. |
| **Go to previous** jumps to the previous timestamp or the beginning of the animation. |
| **Play/Pause** starts or stops the animation. |
| **Go to next** jumps to the next timestamp or the end of the animation. |
| **Go to last** jumps to the last keyframe. |
|
| **Animation timeline/slider**: drag to move the animation to the required point in time. |
| **Timestamp** drop-down menu: select a timestamp to jump to. |
| **Speed** drop-down menu: select the playback speed. |
| **Zoom in** zooms in on the timeline. |
| **Zoom out** zooms out on the timeline. |
| **Zoom to fit** fits so the whole timeline is visible. |
|
| **Player** goes back to animation player. |
| **Magic keyframe** creates a keyframe for all currently placed objects that are selected in the animation editor hierarchy, using their current settings. |
| **Magic keyframe delay** sets the automatic delay that is added between magic keyframes. You can enter values such as `2.5 s`, `5 s`, `10 s`, or `1 min`. |
|
| **Play/Pause** starts or stops the animation. |
| **Expand/Collapse** brings up extended animation tools or closes them. |
| **Add keyframe** adds a keyframe for the selected animation parameter. |
| **Remove keyframe** removes the selected keyframe. |
| **Remove parameter** removes the selected parameter row. |
| **Transition curve view** shows the transition curves, including lines and splines, between values. Drag them to change their shape. |
|
| **Zoom in** zooms in on the timeline, centring on the currently selected position marked by the red line. |
|
| **Zoom out** zooms out on the timeline. |
|
| **Add timestamp**: drag and drop this button onto the timeline to create a new timestamp. A dialogue box then appears, allowing you to name the new timestamp. If you drag an existing timestamp, this icon changes into a bin icon. Dragging timestamps into it deletes them. |
|
| **Zoom to fit** adjusts the view to display the entire timeline. |
| **Project tree** contains all items, parameters etc. involved in this animation. |
| Displays all **Parameters** of the currently selected item in the project tree at the current timeline position. You can edit these parameters by clicking on their values. |
| **Timeline** The red line is the time slider and shows the current animation position. Drag it to change the current point in time. The blue dots are parameter keyframes for the adjacent item in the project tree; drag them to adjust their positions. |
4. Move the crane to the required position and press the **Magic keyframe** button again.
5. The animation can now be played in **Player** or **Edit** mode.
---
# UDiTH App — AppControls
# AppControls
AppControls are a feature introduced in UDiTH Version 7.0. They allow regular users, power users, and administrators to extend the functionality of UDiTH. AppControls run inside an embedded browser within UDiTH, allowing them to present their own user interface directly in the application. Communication with UDiTH takes place through an API.
## Using AppControls
AppControls can be stored in the **Files** tab.
1. To create a new **AppControl**, use **Add** to add a new AppControl element in the **Files** tab.
2. Choose the input source. You can provide either a URL or an offline AppControl from your files.
3. Once it has been saved, you can open it by double-clicking it or by clicking the eye icon next to it.
4. The **AppControl** then opens in a separate window.
## Understanding AppControls
AppControls are designed to handle tasks that are not covered by standard user interface components. These customised forms can be used for data entry, information display, preference settings, and more.
They can also be tailored to match your application's specific user interface, requirements, branding, and interaction style.
## When to Use AppControls
AppControls are particularly suitable in the following scenarios:
1. **Specific Functionality:** Your application requires a user interface element that cannot be achieved with standard controls, such as complex data visualization, custom input validation, or specialized data manipulation.
2. **Branding and Aesthetics:** You want to create a consistent and unique look and feel for your application, aligning with your brand identity or user experience goals.
3. **Usability and User Experience:** Custom forms can be designed to enhance the user experience by simplifying complex tasks or streamlining workflows.
## Offline AppControls
UDiTH allows you to embed AppControls directly within the UDiTH tree. This removes the need for a separate web service to access the AppControls. However, certain restrictions still apply.
## Implementing AppControls
For guidance on creating AppControls, please visit the https://github.com/caxperts/AppControls repo, which contains samples and instructions.
## Security
An allowlist is used to ensure that only the AppControls included in that list can be displayed and access the model. This list is stored in a file named `appcontrols.json`, located in the model's `Data` folder. For more information, please visit the [AppControls security documentation](https://github.com/caxperts/AppControls/blob/main/wiki/Security.md).
---
# UDiTH App — WebSocket Feature
# WebSocket Feature
As of UDiTH 2026.2.0, the API supports WebSocket connections between UDiTH App and AppControl Apps. This allows an AppControl App to run in a separate browser window, independent of the UDiTH App.
## Connection Establishment
The general workflow for establishing a connection is as follows:
1. Open the UDiTH App (running locally, not BBV).
2. Open an AppControl web page.
3. On the first attempt, the browser will ask whether the connection should be allowed:
The answer is stored in the local browser.
4. The UDiTH App will ask whether the WebSocket connection should be established:
## Handling Multiple Instances
The AppControl API connects to the first locally running UDiTH App (first in terms of startup time). If additional AppControl Apps are opened, they also connect to the same first UDiTH App. Locally running UDiTH Apps beyond the first one are ignored.
## Troubleshooting
The connection can be refused from two sides: in the UDiTH App and in the browser. These refusals are the typical causes for unsuccessful WebSocket connections.
### Revoking Connection Refusals in UDiTH App
At the bottom of the **Expert Settings**, use the **Clear dis/approved AppControl urls** button to reset all previously approved or denied AppControl URLs.
### Revoking Connection Refusals in the Browser
Click on the lock icon next to the URL bar:
Then set **Apps on device** to **Allow** or **Ask**:
### Disabeling WebSocket API in an App
Add this code snippet before calling the first API
```typescript
import { Api } from "@caxperts/universal.api/Internal/APIConnector";
Api.disableWebsocketApi = true;
```
Further Information and samples using AppControls and the Universal.API can be found via https://github.com/caxperts/AppControls
---
# UDiTH App — Comment
# Comment
## Quick Comments
|
| 1. Select an object. 2. Go to the **Files** tab and select **Comment** from the **Add** drop-down menu. 3. Enter your text in the box to add a comment to the model. |
> You can **drag attributes** from the menu on the right into the main window. These attributes are treated as comments and linked to their object.
### Changing and Deleting Comments
To change a comment, click it so that it is highlighted in red, then enter the new text. Alternatively, you can drag a new attribute into the main window.
| To delete a comment, select it and click the **Remove** icon in the top toolbar. |
|
| To reselect the object linked to the comment, click the **Select** icon. This allows you to move the comment line to a different object. A red marker appears to help you position it accurately. |
|
| To edit your comment, simply double-click the **Comment** or click the **(Un)Lock** icon. |
| Click this icon to **hide comment line**. This feature is especially useful in the 2D environment. |
|
| To **hide** a comment, toggle this icon. |
This is ideal for editing longer comments that are too long for the name field.
Once you have finished editing the comment in the panel, apply the changes by clicking **Apply text**.
---
# UDiTH App — Drawing
# Drawing
| UDiTH can automatically create a technical **Drawing** from the 3D model. |
3. The name you define for the drawing, for example `DrawingXYZ`, is displayed within the drawing if a text field in the drawing border file (`.svg`) is marked as `###DRAWINGNAME###`.
4. After choosing the name, select the template you want to use. The list shows all templates defined in `drawingtemplates.json`.
* If the **volume clipping tool** is used, the drawing creation process takes the clipping into account and draws only the parts inside the specified volume.
* You can create a drawing of the selected 3D objects only by using the **Draw selected objects only** checkbox.
* The **Use colours** checkbox draws the objects using the same colours as in the 3D model instead of creating them in black and white.
The images below show an example of an isometric drawing created in the UDiTH Demoplant using **volume clipping** and the **Draw selected objects only** option.
## Viewing the Drawing
| Drawings can be opened by clicking the **Open** button next to the drawing in the **Files** tab. |
|
| To **save** any work on drawings, a licence is required. Drawings can be saved as **.svg**, **.pdf**, **.acad.pdf**, and **.png** files. |
|
| The **Markup** tool can be used to create editable screenshots in UDiTH. When you add a Markup, a screenshot is taken from the current camera position. |
2. Enter a name for the **Markup**.
3. Click the **(Un)Lock** button next to the Markup to open the editing tools.
4. The **Markup** editing tools are available in the additional context menu on the right:
|
| **Show initial screenshot** displays the view that was captured when the Markup was created, without any user interface elements. |
| **Undo/Redo** undoes a single action or restores it if it was undone. |
 | **Draw free line** creates a freehand line that follows the movement of the mouse or finger in any direction. |
 | **Draw straight line** creates a straight line in the direction of the mouse or finger movement. |
 | **Draw orthogonal line** creates an orthogonal line aligned with the X and Y axes. |
 | **Draw rectangle** creates a rectangle whose size is defined by the mouse or finger movement. |
 | **Draw oval** creates an oval whose size is defined by the mouse or finger movement. |
 | **Draw text** creates a text field at the position where you click. The font size and colour are defined by the pen settings. If you select existing text, it can be edited. |
 | **Move** allows you to move the currently selected element in any direction on the P&ID. |
 | **Eraser** removes parts of positioned markups graphically. It does not delete entire objects, only the parts over which the tool is moved, similar to using a sponge. |
| **Pen templates** set the drawing pen to a fixed size and colour. The last template is opaque. |
| **Pen definition** changes the size and colour of the pen. |
| **Pen colour** - Click the colour panel to open additional colour options. The slider controls the transparency. |
### Creating and Loading Folders/Packages
  
| Load or create a new folder or package by clicking the relevant icon. You then gain access to the **Definition** area, where you can add definitions and connect them using logical operators. |
| If a folder or package already exists before you load another one, you can either **replace** the existing folders or packages or **expand** them. |
### Deleting and Saving Folders/Packages
|
| Delete a folder or package by selecting it and then clicking the **Delete** icon. You are asked to confirm that you want to delete the folder together with all its contents. |
| Clicking the **Save** icon always saves the entire folder structure, regardless of what is currently selected. A message appears if there are any empty definition groups. |
| Options | |
| **Condition by attribute** | **Condition by volume** |
|---|---|
| -Equal | -Includes |
| -Not equal | -Overlaps |
| -Like (wildcards) | -NotOverlaps |
| -Not like (wildcards) | -NotIncludes |
| Define a volume in the same way as for volume clipping. All objects that are completely inside, or respectively outside, this volume become part of the package. |
| You can choose an attribute, such as approval status or area, and use a text or number string to define the objects you want to include together with a matching condition. |
|
| With an IntelliGroup, you must choose a radius. All objects that are at least partly inside that radius are included in the package. A radius of `0` means that the objects are touching an object in that group. |
You have a model with a restricted area for security reasons. If you need to share the model with contractors while keeping that area hidden, you can do so by placing the restricted section in a package. This requires rules based on attributes and volumes.
| If you want to exclude the selected parts of your model, you can do this by the following steps: | |
|---|---|
|
| Create a new package. |
|
| Select all objects you want to exclude. In the definition area, click **Condition by volume**. |
|
| Clicking the highlight icon shows that the selected volume also contains some small pipes and structural parts that should not be part of the package: |
|
| To exclude the structural parts, create a new condition. This time, choose **Condition by attribute**. |
Because the **FileName** attribute of all objects that are to be excluded contains **Structure**, select **FileName** under **Available attributes** and enter **Structure** in the text box. In this case, you can use either exact (`Structure`) or fuzzy matching.
Now choose **AND NOT** as the logical connection so that all objects included by the first condition remain inside the selection, except for the objects defined by the second condition.
To exclude the two nozzles, select them and create a **Condition by volume** using **Includes**.
Connect that condition with **AND NOT**:
> This is only one of many possible ways to get this result.
|
| The last step is to save your package by clicking on the icon **Save package**. Enter a name and choose a file format. |
|
| Cancel or retry. |
|
| Capture photo. |
|
| Switch camera. This requires multiple available cameras. |
> Markers can be renamed, enabled, or disabled.
|
| **View** returns the camera to the position of the POI marker. |
---
# UDiTH App — Report
# Report
UDiTH includes a powerful yet easy-to-use reporting engine.
To create a report, click **Add** in the **Files** tab and then select **Report**.
## Report Definition Dialogue
The report definition selection shows a list of predefined reports. These are defined in the Excel file **IntelliPidReportDefinition.xlsx**.
> For more details about predefined report definitions, see **Report definitions** in the **Custom settings** chapter.
When you select a report definition, the report results page opens and additional filters can be applied. Two buttons are available next to each report definition:
| **Report Settings** This opens the Report Editor and allows you to modify the predefined report definition. For more details, see **Report Editor** below. |
|---|---|
| **Save Report** This opens the save dialogue directly. You can save the report results as an **.xlsx** or **.csv** file for further use outside UDiTH. |
The **Reset** button clears the **Selected attributes** table. All other settings remain unchanged.
Click **OK** to generate the report and display the **Report Results** view.
## Report Results
The report results are displayed in the **Report Results** screen. The screen is divided into the **Report Menu** on the left and the results grouped by attributes. You can select multiple results by holding down the **Ctrl** key while clicking the lines:
### Report Menu
The report menu contains functions that help you narrow down the results, locate items on the P&ID, or export the results:
 | **Reload Report** - Updates the report, for example if custom attributes have changed. |
|---|---|
| **Fit in model** - Highlights the selected items in the corresponding P&IDs or 3D tabs. If the P&IDs are not already open, they are opened automatically and shown in the tab bar. |
 | **Select underlying objects** - This function currently produces the same result as **Fit in model**. |
 | **Copy current report definition** - Copies the current report definition to the clipboard so that it can be saved in the report definition file. For more details, see **Report definitions** in **Custom settings files**. |
| **Customise Report Settings** - Opens the Report Editor and allows you to modify the current report definition. For more details, see **Report Editor** above. |
 | **Toggle quick filter** - Toggles the quick filter to narrow down report results. When activated, another line is shown below the attribute names. Wildcards can be used: |
| The line consists of a filter string field and two additional buttons: | |
 | **Hide/show exclusive clauses** - Allows you to set additional filters to show or hide exactly defined values and displays the current number of values set. |
| **Clear filter** - Clears and resets all filters. |
 | **Filter combine mode** - If several filters are set, they are combined with an **OR** operator by default, meaning only one filter condition must be true. If you switch to **AND**, all filter conditions must be met for an item to be listed. |
All lines with the corresponding values are then either shown or hidden in the results list.
### Custom Attribute Editing
If multiple lines are selected and a custom attribute with a CodeList is included in the report, changes can be applied in bulk to all selected items:
> For even more detailed reporting and advanced reporting features, use **CAXperts UniversalReporter**.
### Filter and Sorting
You can **sort alphabetically** by clicking an attribute. **Combine** multiple search strings with a **space**, and **exclude** search strings by using **!**.
---
# UDiTH App — Screenshot
# Screenshot
You can capture and save your current viewing perspective as a screenshot. Click **Add** in the **Files** menu and select **Screenshot**. Your current view is saved as an image, which you can rename, save, and open again later.
|
| Captures the current viewing perspective as a screenshot. |
|
| Saves the screenshot to the current device. |
|
| Opens the screenshot for viewing. |
Click **Files**, then **Add**, and then select **Sketch**.
This adds a new sketch layer to your model, allowing you to place custom objects without directly changing the model itself.
You can open multiple sketch tabs, but only one sketch is displayed at a time. Click **3D** in the bottom-left corner to return to the model.
| Button | Description |
|---|---|
|
| **Delete** the selected sketch item. |
| Convert 3D view objects to sketch items, which hides the source object, or clone them, which keeps the original visible. During conversion or cloning, you are prompted to choose between **referencing** and **copying**. - **Referencing** links the **Sketch** item to the 3D object by its ID, maintaining its appearance despite model changes. - **Copying** creates a new independent sketch item with normal behaviour. |
|
| **Undo** the last change to the tree. |
|
| **Redo** the last undone change to the tree. |
There are five object categories:
* **Basic structure** (ground plate, column, steel, slab)
* **Basic shapes** (cube, vertical/horizontal equipment, sphere)
* **Piping** (pipe, valve, ball valve, strainer, flange, etc.)
* **Platform**
* **Custom objects**
You can still use the standard functions in the left-hand menu. In addition, the sketch tab menu provides further options for editing the selected object.
### Example
#### Basic Structures and Shapes
Basic structures and shapes have a default scale and editing options that depend on their function:
| Object | Default scale | Scaling options | Property to choose from |
|---|---|---|---|
| Ground plate | 10 x 10 m | X, Y & Z | - |
| Column | 0.3 x 0.3 x 3 m | Height only | Profile type |
| Steel | 0.05 x 0.05 x X m | Length only | Profile type |
| Slab | 1 x 1 x 0.2 m | X, Y & Z | - |
| Cube | 1 x 1 x 1 m | X, Y & Z | - |
| Sphere | 0.1 m | Z | - |
| Vertical / horizontal equipment | 2 x 1 m | X, Y & Z | - |
| Pipe | 1 m, DN 50 | Length only | Length and diameter |
| If you want an object's dimensions to match the position of another object, select the object, click the scale icon, and then click and hold one of the semi-spheres on the selected object. When you move the mouse pointer over another object in the model, a green circle with crosshairs appears. The crosshairs indicate the X, Y, and Z coordinates at which the scaling will end. |
| When placing a pipe, you automatically get additional options that allow you to create a pipe run and connect it to other pipes or Symbol Designer objects with piping connectors. |
| The pipes diameter can be chosen from a drop-down list in the properties. |
| You can add a 90° angle to the end of the pipe run by dragging the half-sphere, and you can move or lengthen the pipe by dragging the coloured arrows. | |
| In rotation mode, you can drag the curved arrows to change the angle of the pipe. Pressing **Ctrl** makes the pipe end point towards the mouse position. |
| The easiest way to create a pipe run is to click to where your pipe should start. | |
|
|
| You can add additional pipes between bends or loop pipes back on themselves. |
| Start by placing the platform. Click the **Platform** icon and then click any location in the model, or drag the button into the 3D space. |
To select the whole platform, select any part of it and then click that selected part again.
The Platform can be moved and scaled as a whole, but its columns and slabs can also be moved, scaled, and changed independently.
The platform attributes include buttons for increasing or decreasing the number of columns and rows. Deleted platform objects can be reactivated with the **Activate** button. You cannot reactivate individual objects, so unnecessary parts must be deleted again.
### Custom Objects
Custom objects in the **.obj** format can be placed like other **Sketch** items. Click the button and select the object to be created in the file browser.
### Adding Objects from the Catalogue
When loading a model, UDiTH looks for a **Catalogue** folder with subfolders for objects, for example `Architectural`. The **Catalogue** folder must be in the same location as the **Data** folder.
> The 3D **Catalogue** in UDiTH also supports **.obj** (Wavefront) files.
The UDiTH **Catalogue** includes **.obj** or **.xls** files with corresponding **.jpg** or **.png** images. The **UDiTHsketchitemindex.txt** list file, located in the model's **Data** folder, contains all available items. The default **Catalogue** includes common plant parts such as pumps and vessels, which are available as regular objects. Although objects can be scaled, only parametric symbols retain the correct proportions.
#### Adding Objects to the Catalogue
To expand the UDiTH **Catalogue**, add any **.obj** file together with an optional **.jpg** or **.png** image. UDiTH automatically includes these items when the model is loaded, provided they are valid and correctly listed in **UDiTHsketchitemindex.txt**. Both absolute and relative paths are supported, including **#include**.
Example:
Catalogue/Ladder/ladder1.obj
/Ladder/ladder2.obj
\#include D:\\yourindex.txt
Using **#include**, objects can be stored in multiple locations as required. The included text file works in the same way as **UDiTHsketchitemindex.txt** and can also contain additional includes.
The creation of a **UDiTHsketchitemindex.txt** file can be automated by
creating a **.bat** file with the following lines of code:
\@echo off
for /f \"delims=\" %%i in (\'CD\') Do set wdrive=%%i
Setlocal EnableDelayedExpansion
if exist UDiTHsketchitemindex.txt del UDiTHsketchitemindex.txt
for /r %%a in (\*.obj,\*.xlsx) do (
SET out=%%a
rem set out=!out: =%%20!
set out=!out:d:\\\_DemoPlant\\\_\_work\\20_config\\=!
rem set out=!out:\\=/!
set out=!out:%wdrive%=Catalogue!
echo !out! \>\> UDiTHsketchitemindex.txt
)
Executing this batch file in the root folder of the catalogue that contains all subfolders and objects will delete any existing UDiTHsketchitemindex.txt file and create a new one containing all \*.obj and all \*.xlsx files in all subfolders.
#### Adding Parametric Symbols to the Catalogue
Parametric symbols are created using **3D SymbolDesigner**.
These symbols can contain attributes that change the appearance of an object, allowing complex objects such as the vehicle crane shown below, with movable parts, to be designed. The white spheres in the images represent movable parts and can be dragged to change certain attributes of a symbol, for example raising the crane. For a detailed explanation of how to create symbols, please refer to the **3D SymbolDesigner** manual.
To add parametric symbols to the catalogue, add the relevant **.xlsx** file created by **SymbolDesigner** to **UDiTHsketchitemindex.txt**, for example:
### Converting Objects from the 3D Model
In this example, a tank is moved and connected to an existing pipeline.
Select the tank and its nozzles and open the **Convert** menu. Click the first button, **Convert 3D object to sketch item**, and choose **Reference**, because the original tank is to be moved.
Click **Move** and drag the red and green arrows until the tank is next to the pipeline.
Select the pipeline you want to connect to the tank, open the **Convert** menu, and click the last button, **Convert 3D view objects to piping**.
---
# UDiTH App — Spraying
# Spraying
|
| The **Spraying** feature allows you to select segments within a **3D laser scan object** in detail and either export or remove the selected parts from the model. |
|
| **Volume clipping** generates a clipped area from the previously sprayed and selected surfaces. |
| **Pen** sets the drawing pen to a fixed **radius** and colour. You can also define a maximum **distance**. |
|
| Clicking the **Views** icon opens the views panel in the menu on the right-hand side. There, you can save, delete, and edit views for the current session. |
When saving a view, you can enter a name and choose which information to include:
| - Colours and visibility - Position - Highlighting - Clipping - Active aspects - Day/night cycle |
|
| UDiTH **Settings** offer a wide range of configuration options and allow you to customise many aspects of the application. |
You can show or hide selected objects.
#### Attribute Options
1. **Empty attributes** shows or hides attributes that have no values.
2. **Configure priority attributes** determines which attributes are shown first, and in which order, when you hover over an object.
3. **Preview attribute limit** determines how many attributes can be previewed when hovering over a 3D object.
4. **Limit for automatic labelling** determines how many labels can be shown at the same time in the 3D view.
#### Units
Choose the unit to be displayed when measuring or adding objects.
> This does not apply to attribute information.
#### 3D User Interface
**(navigation and drawings)**
- **Common views cube** shows or hides the navigation cube in the upper-right corner of the 3D view.
- **Minimap** shows or hides the minimap in the bottom-right corner of the 3D view.
- **2-sided ISO perspective** determines the side towards which 2-sided ISOs face.
- **Use Common Views XYZ-Mode** changes the view cube labels from compass directions, such as North and South, to Cartesian XYZ labels.
- **360° Panorama** shows or hides the red spheres that indicate panorama positions.
##### UI Options
You can adjust the scale of the user interface from `0.6` to `2.0` and change the attribute font size from `2` to `6`.
> Changes to these settings take effect immediately, but you must save them in a configuration file if you want to keep them after closing UDiTH.
#### 3D Rendering
Option height map for **Texture mode** (Normal, Height Map, No Texture) creates a height map for the 3D model and colours objects accordingly.
**Use camera position as light source** works similarly to a flashlight.
**Use old camera rotation behaviour** changes the camera behaviour back to that of older UDiTH versions, rotating around the centre of the screen instead of around an object.
**Hide movement indicators** hides the spheres that show the point around which the camera is rotating.
#### Color Options
Here you can change the colours or patterns of the specified objects.
#### Day and Night Cycle
UDiTH includes a day/night cycle with shadow simulation. You can decide at which time the simulation starts.
The time multiplier increases the speed at which time passes in the 3D view.
#### Expert Settings
Advanced users can adjust the cache size, the maximum number of triangles, and the maximum camera range to suit their needs.
 **Triangles limit**
| Limits the maximum number of triangles the system can load. |
 **Render quality level**
| **Low:** 30 FPS. **Medium:** 30 FPS with ambient occlusion. **High:** 60 FPS with ambient occlusion and shadows. |
 **Memory mesh cache size (triangles)**
| Limits the model cache size by the number of accessible **triangles**. |
 **Memory model cache size (bytes)**
| Limits the model cache size by the number of accessible **bytes**. |
 **PDF projection max render jobs**
| This setting refers to PDF rendering while zooming in and out. It limits the number of parallel rendering jobs or panels. |
| **Show licences:** | Opens a new tab with legal information about the software and licences used in UDiTH. |
| **Viewer version:** | Shows the version of UDiTH you are using. |
| **Model version:** | Shows the version of the model you are using. |
| **Builder version:** | Shows the version of UDiTH Builder the model was created with. |
| **Conversion date:** | Shows the conversion date of the model. |
| **Expiration date:** | Shows the date until you can use the current model. |
#### Automatic Labelling Settings
#### Priority Attributes Settings
Priority attributes are always displayed first in the attributes panel. This does not affect custom attributes, which are always displayed directly after the attribute to which they are attached by definition. If the item under the mouse pointer does not contain one of the selected priority attributes, the next available attribute is displayed instead.
### General Information
| Colour settings | |
|---|---|
| Highlight | Changes the highlight colour of selected elements. |
| Selected elements | Changes the colour of selected elements. |
| Sheet background | Changes the P&ID background colour. |
| Background elements | Changes the colour of non-highlighted elements. |
| General settings | |
| Text offset | Changes the distance of the element-descriptions to the elements themselves. |
| Select attributes for automatic labelling | Opens a selection window for choosing attributes for automatic labelling. To select an attribute, drag and drop it into the list on the right. |
| Configure priority attributes | Opens a selection window for choosing priority attributes. To select an attribute, drag and drop it into the list on the right. |
| Preview attribute limit | Defines the maximum number of attributes displayed in the tooltip that appears when you hover over an item. Attributes that are not available are ignored. |
| Legend Font size | |
| Font size | Changes the font size used in the P&ID legend. |
| UI options | |
| UI scale | Changes the scale at which all user interface (UI) elements are displayed. |
| Reset UI scale | Resets the UI scale to normal (factor 1). |
| Attribute font size | Changes the font size used for attributes in the panel on the right. |
2. **Bearing** indicates the deviation of your plant from true north. You can determine this in Google Earth by using the measurement function to draw a line in the direction of plant north. The resulting **Heading** value can be used as the bearing.
3. **ModelLocation** refers to the model coordinates of your reference point.
Use those model coordinates directly for **ModelLocation**.
> GPS altitude data is not sufficiently accurate, so instead of using it directly, add `1.5` metres to the Z coordinate.
---
# UDiTH App — Advanced options
# Advanced Options
## Output settings in UDiTH Builder
When you prepare a model in **UDiTH Builder**, you can allow or prohibit downloads in the **Output configuration** and set the default type of **Common views cube** display, either directional or XYZ.
You can also enter an **expiration date** for your model. This must not be a date in the past. Once the model has expired, it can no longer be opened.
You can also include an optional **colour configuration file** (`.xlsx`) to be loaded by default, as well as a **colour files directory** that opens when you click **File management > Load a colour file**.
In the same way, you can include a link mapping file and an attribute mapping file, which defines links between the P&ID and the 3D model.
## Set a Password for Your Model
| If you are providing a model using HTTPS, you can **protect access** to your model by using **HTTP Basic Authentication** with a user name and password. |
| **Windows authentication** is also supported. |
**Triangles limit** - the number of triangles from which your 3D model is built. UDiTH uses more triangles for objects closer to the camera, so objects in the distance may appear less detailed or may be missing parts.
**Render quality level**
- *Low*: shading and ambient lighting are disabled.
- *Medium*: only ambient lighting is disabled.
- *High*: all quality settings are enabled.
**Memory mesh cache size (triangles)** specifies the number of triangles the model is allowed to use for caching.
**Memory model cache size (bytes)** determines the amount of memory reserved for caching your model.
**PDF projection max render jobs** limits the rendered area of a PDF projection. This is mainly important when several PDFs are used.
You can add objects to the **Catalogue** under **Additional items**. To do this, place your **.obj** files, together with an optional preview **.jpg** image at `64 x 64` pixels, in the `Catalogue` folder in the same location as `UDiTH.exe`.
Add the text file `UDiTHsketchitemindex.txt`, containing the file paths to all objects, to the same folder.
For example, the file may contain:
```
Catalogue\\HeatExchanger\\Type 1.obj
Catalogue\\Pumps\\Type 1.obj
Catalogue\\VerticalVessel\\12m2.obj
```
## Adding Predefined Clippings
If you have saved a clipping to the clipboard, you can store it in an Excel file:
| minY | minX | minZ | maxY | maxX | maxZ | |
|---|---|---|---|---|---|---|
| NewVolume | 3023.24 | 2375.12 | 67.19 | 3037.24 | 2393.118 | 72.14 |
The IntelliPID module interface is divided into the following areas:
- The central P&ID viewport where the P&IDs are displayed.
- The breadcrumb hierarchy (red), which is used to navigate the P&IDs by hierarchy.
- The left menu bar (blue), attached to the left edge of the screen.
- The right panel (green), which shows the Files panel, Attributes panel, or Advanced search. These panels can be rearranged and resized through the multi-window functionality.
- The tab bar (orange) at the bottom of the screen, showing 3D, open P&IDs, or documents.
More details about these areas and their integrated functions are provided in the following chapters.
## Left menu
The left menu is the main menu for UDiTH and provides access to the central functions available from all views.
## Search in Current IntelliPID
| The **Search in IntelliPID** button opens a search field, shown above, that searches the currently displayed P&ID for the entered string. The number of matches is shown to the right of the search string. All matches containing the requested string are included. Wildcards are not supported. |
| The arrows to the right of the match count are used to navigate between the matches. The down arrow jumps to the previous match. |
| The up arrow jumps to the next match. |
| **Pan Mode** activates the panning function. Alternatively, press and hold the middle mouse button, press and hold the mouse wheel, or, if neither is available, press the left and right mouse buttons simultaneously. On mobile devices, swipe the screen with two fingers to pan. |
| **Zoom in or out** by using the mouse wheel or by pressing and holding the right mouse button and moving the mouse up or down. On a touch screen, pinch apart to zoom in and pinch together to zoom out. | |
| **Zoom by rectangle** zooms the screen to the marked region on the P&ID. |
| **Fit Page** centres the screen on the selected elements and zooms to fit them into the viewport. If no object is selected, the current P&ID is zoomed to fit into the viewport. |
| **Refresh Graphics** resets the current P&ID in the viewport to its original state. |
|
Users can change the display colour of selected objects by opening the colour menu. This menu is divided into four main sections, as shown below:
|
| **Advanced colour selection** opens a pop-up menu for detailed colour selection, allowing the user to choose from the full RGB colour spectrum. |
| The **colour picker** allows the user to pick a colour from a 2D object and save it to **Custom colours**. This can then be selected from the colour palette just like the standard colours. When this feature is enabled, first click the object from which you want to take the colour, then select a custom colour square to assign the selected colour to it. |
| The **Clear style** button restores the assigned colour of the selected objects to the default colour defined when the model was created. |
| The **Reset all colours** button restores **all** assigned colours for **all** objects to the default colours defined when the model was created. |
| **Go to P&ID** – When an OPC (off-page connector) is selected, clicking this button opens the linked P&ID or PIDSketch loaded in the Files tree. The view then zooms to the corresponding OPC on the linked P&ID or PIDSketch. |
| **Close all IntelliPID tabs** – Closes all currently open P&IDs and removes them from the tab bar. All unsaved PIDSketches, markups, and colouring are discarded. |
| The **Tools menu** contains some useful tools for visualization of IntelliPID content. When clicked, the menu opens to the right showing the contained tools: |
| **Automatic labelling** – Places labels automatically on the currently displayed P&ID. The labels are applied according to the automatic labelling settings if the objects contain one of the attributes defined in the [**Settings**](#settings) panel. |
| **Highlight linked objects** – Helps users identify objects that have been successfully linked to the 3D model. For these objects, an intelligent link between the 3D model and the P&ID is active. |
| The **Custom Attributes** button is visible only when custom attributes have been defined in a custom attributes definition file. Further information about these files, including their creation and syntax, can be found in **Custom Attributes** in the chapter [**Custom settings**](#custom-settings). |
The button opens a custom attributes panel in the right panel:
#### Custom Attribute tool bar
| **Export all changes** – Saves all data entered into custom attributes in a single `.xlsx` file together with the relevant information for the items to which the values are linked. |
| **Import all changes** – Loads previously saved custom attribute values from an `.xlsx` file back into the custom attributes. |
| **Send email** – Changes to the custom attributes are logged during the session. Clicking this button generates a list of changes and copies it to the clipboard. A new email is then opened in your default email client. The default recipient and subject are defined in the `Meta` tab of `IntelliPIDattributes.xlsx`. See [**Custom settings**](#custom-settings) for more details. |
| **Show only active** – Custom attributes not used in the currently displayed P&ID are hidden from the list of used values for that P&ID and from the corresponding legend. |
| **Place legend** – Displays a legend with the corresponding custom attribute colour keys on the P&ID. This legend can be moved by dragging it to any location on the P&ID. See the description of custom attribute CodeLists and legends below. |
#### Custom Attribute Drop-down
This drop-down control allows the user to select from custom attributes with CodeList definitions. By default, none is selected, and the P&ID colouring remains unchanged.
When a CodeList custom attribute is selected, the objects in the P&ID are coloured according to their custom attribute values and the legend is displayed below.
#### Legend
The legend provides colour information for the custom attribute selected from the drop-down described above. Unused values can be hidden using **Show only active**.
The displayed values and their corresponding colours are shown in the placed legend.
The legend can be resized.
#### Settings
|
Opens the settings panel for UDiTH. Users can configure the main P&ID settings in all options containing `IntelliPID` in their description:
|
| Setting | Description |
|---|---|
| **Color options** | |
| Highlight | Changes the highlight colour of selected elements. |
| Selected elements | Changes the colour of selected elements. |
| Sheet background | Changes the P&ID background colour. |
| Background elements | Changes the colour of elements that are not linked to the 3D model. |
| **General settings** | |
| Text offset | Changes the distance between element descriptions and the elements themselves. |
| Use flat IntelliPID hierarchy | Changes the breadcrumb hierarchy from structured view to flat view. |
| **Attribute options** | |
| Select attributes for automatic labelling | Opens a selection window for choosing attributes for automatic labelling. To select an attribute, drag and drop it into the list on the right. |
| Configure priority attributes | Opens a selection window for choosing priority attributes. To select an attribute, drag and drop it into the list on the right. |
| Configure visible attributes | Defines the maximum number of attributes displayed in the tooltip that appears when you hover over an item. Attributes that are not available are ignored. |
| **Legend Font size** | |
| Font size | Changes the font size used in the P&ID legend. |
| Use default legend position | Enables the use of a default legend position, when one has been defined. |
| Use colorful legend names | The legend description names are coloured according to the legend content. |
| **UI options** | |
| UI scale | Changes the scale at which all user interface (UI) elements are displayed. |
| Reset UI scale | Resets the UI scale to normal (factor 1). |
| Attribute font size | Changes the font size used for attributes in the panel on the right. |
| **P&ID Sketches** | |
| Snap mode ON | Activates snap mode during PIDSketch mode. The snapping option can also be turned on or off using the hotkey `Ctrl+F` while PIDSketch edit mode is active. |
| **P&ID Grid options** | |
| Show grid | Activates the grid on the IntelliPID canvas. The grid can also be turned on or off using the hotkey `Ctrl+G`. |
| Grid opacity | Modifies the intensity of the grid display. |
| Width value | Modifies the width of each cell on the grid. |
| Width unit | Selects the grid unit system (mm or inch). |
| Use dynamic width | Activates the predefined dynamic grid width. The user can select a width unit: fine, normal, or coarse. |
| **Expert Settings** | |
| Align custom symbol leader lines automatically | Forces automatic connection of the leader line when a `connecteditemid` attribute exists. |
| Use objects center for leader line | Uses the centre of the object as the default connection point for the leader line of the custom symbol. |
#### Priority Attributes Settings
Priority attributes are always displayed first in the attributes panel. This does not affect custom attributes.
Custom attributes are always displayed directly after the attribute to which they are attached by definition - see [**Custom Attributes**](#custom-attributes) in [**Custom settings**](#custom-settings).
If the item under the mouse pointer does not contain one of the selected priority attributes, the next available attribute is displayed instead.
#### File management
| Opens the Files panel. See [**Files panel**](#files-panel) for more details. |
| **Open manual** – Opens the link to the manual on CAXperts Help. |
It provides access to the following views and features, which are described in the following chapters:
- **Attributes panel**
- **Advanced search panel**
- **Files panel** (optional)
The panel tabs can be rearranged and resized through the multi-window functionality:
### Advanced Search
In addition to **Search in Current IntelliPID**, UDiTH includes an advanced search function designed for working with both 3D models and 2D drawings. The results are displayed according to the attributes in which the string was found. The number shown after each attribute indicates the number of matching groups in that attribute, using the same colour for hard matches and grey for soft matches, as well as the number of affected P&IDs in blue. When an attribute is expanded, the matching groups are displayed as a list with the corresponding P&ID name shown in blue.
### Attributes Panel
The **Attributes** tab is displayed by default at start-up. It contains all attribute information for the selected item or items provided during the building process, whether from the authoring system or the UDiTH SDK.
## Files Panel
The Files panel is the central location for UDiTH files attached to the model. All sketches, markups, comments, views, and similar items are displayed in a tree structure that makes it easy to navigate through all attached files.
Although all nodes in the tree are always visible, there are some differences in file creation between 3D and IntelliPID. This chapter describes the IntelliPID-specific functions together with some general features of the Files tree. The three sections of the panel are:
- **Tool bar** – Tree editing and file operations
- **Model root** – The model root is always present and is the anchor for the tree structure.
- **Files tree** – Contains a hierarchical structure of the files attached to the model.
### Files Tool Bar
#### File Creation
The file creation button is context-sensitive. Depending on the object selected when **Add** is clicked, different options are available. Newly created files are placed beneath the selected file in the hierarchy:
| ||
|
|
|
| **Model root is selected** | **Folder is selected** | **PIDSketch is selected** |
|
**Remove** – Deletes the currently selected node or object from the tree.
If the selected item is a folder, all files inside that folder are also deleted after a confirmation prompt:
|
| **Copy** – Copies the selected tree object. Works for `Folder` and `Markup`. |
| **Undo** – Undoes the last change to the tree. |
| **Redo** – Redoes the last undone change to the tree. |
| **Load** – Opens a file dialogue to select a UDiTH file to load. The loaded file is appended to the Files tree hierarchy automatically. To replace the existing hierarchy, remove it first. |
|
**Save** – Opens the save options:
|
| **Save** – Tree elements can be selected individually for saving. Disabling a folder object also disables all objects within that folder hierarchy. Clicking **Save** opens a save dialogue in which you can choose the file name and location. The designated file type is `*.upvf`. |
|
|
**Save config** – Saves the configuration to a UDiTH file. A configuration includes the following areas:
|
|
**Export to PDF** – Opens a file save dialogue for saving IntelliPID P&IDs in PDF format. In order to export searchable PDFs (Windows only), it is necessary to have installed **Inkscape 1.4.x** on the same device.
Several PDF export options are available:
|
| **As shown** – The P&ID will be exported as displayed, including selection highlighting and display styles. | |
| **As modified** – The P&ID will be exported as displayed, selection highlighting and display style are ignored. | |
| **Original** – The P&ID will be exported in its original state, all coloring and sketching are ignored. | |
| A P&ID name filter can be applied to the list of available P&IDs. Users get to select from this list using the following selection and export options: | |
| **Manual selection** – Select P&IDs by clicking on the check box. | |
| **With Sketches** – Selects all P&IDs in the project that have applied PIDSketches. | |
| **Select current** – SSelects only the currently displayed P&ID. | |
| **Select open** – Selects all P&IDs currently open (visible in the tab bar on the bottom). | |
| **Select all** – Selects all P&IDs in the project. | |
| **Zip file** Exports selected P&IDs to PDF in one zip file. | |
| **Concat into single file** – Exports selected P&IDs into one single PDF binder. The drawing names will be exported as bookmarks to make navigation easier. | |
|
**Filter selected files** – selects/unselects elements in a files tree by their type:
|
|
**Select display style** – Opens a pop-up menu for display style selection.
The model is loaded with a default color file, but additionally, users can load coloring settings depending on attribute conditions defined in color files.
|
| **Load link file** – Opens a file system dialogue to load a link file (.xlsx). You can replace existing links or append the existing links with new ones. For more details about the formatting and definition of links, see [**Link Mapping Files**](https://help.caxperts.com/UDiTH%20App/Appendix%20-%20Custom%20settings%20files#link-mapping-files). |
| **Set current legend position as default legend position** – This option sets a current P&ID legend position and size displayed in IntelliPID as the default legend position for all other P&IDs in the current session and can be also stored to default.upvf, if required. |
| **Folder** – Adds a Folder object to the Model root. Subfolder are also supported. In folders, all other types of files can be stored in and thereby grouped. For multiple files to one P&ID, for example, users can create a folder that contains all relevant files for that P&ID. |
| **AppControl** – Creates a new "AppControl" For more details, see the general chapter [**AppControl**](https://help.caxperts.com/UDiTH%20App/AppControls). |
| **Markup** – The markup file enables you to do markups on your P&IDs, including graphical objects. For detailed information, see the following chapter [**P&ID Markup**](#pid-markup). |
| **PIDSketch** – The sketch file enables you to add sketches to your P&ID, including you custom P&ID symbols. For detailed information, see the chapter [**P&ID Sketch**](#pid-sketch). |
| **Report** – This opens the report creation dialogue. Predefined custom and ad-hoc reports can be generated here. For more details, see the chapter [**Reporting**](#reporting). |
| **Comment** – The commenting object contains one comment per node. Comments can be attached to any P&ID element, original or sketch. Commenting objects are always dependencies of a P&ID Sketch object. For more details, see the Chapter [**P&ID comment**](#pid-comment). |
| **Window Layout** – Enables saving and loading of customizable layout or predefined startup views for each UDiTH instance. |
|
| **Edit** – Opens the according file in edit mode. An editor panel is shown in the right panel depending on the file type selected. |
| **Show/Hide** – Shows or hides the according file/object in the viewport. |
| **Show/Hide** **Comment line** – Shows or hides the leader line of the comment. |
| **Select** – Selects and highlights sketch items on a selected PIDSketch. Useful for multi-sketch drawings. |
| **Apply at startup** – This toggle activates automatic loading of the customized window layout on every startup of the UDiTH model. |
|
| The Markup function in IntelliPID is a tool that enables the creation of graphical and textual markups for P&ID (see section [**Files tool bar**](#files-tool-bar) in the chapter [**Files panel**](#files-panel)). |
### Tool bar
| **Show initial screenshot** – Shows a screenshot of the P&ID before Markup was applied. |
| **Show last saved screenshot** – Shows a screenshot of the P&ID in the state when editing was started. This includes Markups made previously. |
|
| **Undo** – Undoes the last action taken in Markup. |
|
| **Redo** – Redoes the last undone action. |
| **Draw free line** – Creates a freehand line following mouse or finger movement in all directions. |
| **Draw straight line** – Creates a straight line in the direction of mouse or finger move. |
| **Draw orthogonal line** – Creates an orthogonal line bound to X and Y axis. |
| **Draw rectangle** – Draws a rectangle. Size is defined by mouse or finger movement. |
| **Draw oval** – Draws an oval. Size is defined by mouse or finger movement. |
| **Draw text** – Creates a text field at the position where the mouse is clicked. Font size and color are defined by the pen definition. If an existing text is picked, this text can be edited. |
| **Move** – Enables you to move the currently selected element in any direction on the P&ID. |
| **Erase** – The erase tool erases graphically the positioned markups. It does not delete coherent objects but rather those parts the tool is swiped over, resembling a sponge. |
|
| The P&ID Sketch feature allows users to sketch into existing P&IDs. Sketches are applied to a separate layer and do not modify the original document. |
### Tab Selector
The Tab Selector allows users to toggle between the P&ID sketch functions, 2D catalog, sketch labels and sketch items presented on the P&ID Sketch.
### PIDSketch Name
PIDSketch name shows the name of the currently open/edited P&ID sketch and the corresponding P&ID number/title in parentheses.
### Tool bar
|
| **Undo** – Undoes the last action taken in PIDSketch. |
|
| **Redo** – Redoes the last undone action in PIDSketch. |
| **Routing** – Starts a line routing process to sketch orthogonal lines. To finish routing, click or tap the button again or use the right mouse button. |
|
| **Free Routing** – Starts a line routing process to sketch lines at a defined angle (default is 45°). To finish free routing, click or tap the button again or use the right mouse button. To resume free routing, hold the Ctrl button and click one end of the line. |
|
| **Free Hand** – Creates a freehand line following mouse or finger movement in all directions. To finish routing, click or tap the button again or use the right mouse button. |
|
| **Polyline** – Creates a straight line in the direction of the mouse clicks. To finish routing, click or tap the button again or use the right mouse button. |
|
| **Circle** – Places a circular typical, e.g. for pumps. When placed, the line (original and sketch) it is placed upon will be interrupted to fit in the symbol. |
|
| **Rectangle** – Places a rectangular typical, e.g. for measurements, indicators, etc. When placed, the line (original and sketch) it is placed upon will be interrupted to fit in the symbol. |
| **Valve** – Places a general valve typical. When placed, the line (original and sketch) it is placed upon will be interrupted to fit in the symbol. |
| **Revision Cloud** – Starts a freehand line routing process to sketch a revision cloud. |
|
| **Text** – Creates a text field at the position where the mouse is clicked. The text value, font, size and individual color can be defined in the text attributes. |
|
**Break line** – Breaks the selected line and creates a separate segment between inline components.
For breaking a straight line into two segments, an object needs to be placed first.
First click on the point you want the break to be placed, then click the Break line function.
Depending on the positioning on the line the break will be applied to the closest end to clicked point:
|
| **Un Break line** – Removes the selected line breaks. |
| **Copy** – Creates a copy of the selected object (works for original and sketch items). The copy is attached to the mouse position and can be placed by clicking on the destination position. |
| **Rotate** – Rotates or mirrors the selected sketch item or a selection of sketch items.Active rotation command is symbolized by the rotation symbol in the center of the sketch item. The rotation commands are activated by clicking/tapping the respective symbol and |
| **45° Rotation symbol** – rotates the sketch item in 45° increments. **Rotation symbol** – rotates the sketch item freely. **Mirror symbol** – Flips the symbol axially in the dragged direction. |
| **Change layer color** – Opens a default color selection pop-up (see section **Colorize selected objects** in the Chapter [**Left menu**](#left-menu)). The color is applied to all sketch items in the current sketch layer. |
| **Hide Objects** – Hides the selected objects on the drawing. |
| **Show Hidden Objects** – Shows hidden objects on the drawing (from hidden layer). |
|
| **Unhide Objects** – Unhides all objects from hidden layer. |
| **Sub Area Colorize Mode** – When activated, the existing fill color of the objects can be changed. |
| **Hotkey** | **Copy & Paste** – Within UDiTH: Press "Ctrl+C" to copy elements. Press "Ctrl+V" to insert the copied elements from the clipboard into the same PIDSketch, another PIDSketch or a new PIDSketch on another drawing. |
| **Hotkey** | **Snap Mode ON/OFF** – Press "Ctrl+F" to toggle snap mode on/off while being in PIDSketch edit mode. |
| **Hotkey** | **Show Grid ON/OFF** – Press "Ctrl+G" to show grid on/off. |
If more attributes are needed, they can be added as necessary in the lower part of the attributes:
Enter the fields marked with "Enter text..." and type in you new attribute name on the left and the according new value on the right (green fields). To confirm the new attribute hit Enter or click on the Add Attribute button (marked red).
The new attribute will appear in the attribute list. If you wish to remove the attribute, click on "delete" symbol
>
The attribute will be deleted then.
The custom and changeable attributes can be predefined in the **intelliPidAttributes.xlsx.** Please see the chapter [**Custom Attributes**](#custom-attributes).
#### Attribute "Style"
Different styles are available (depending on the sketch item) and can be selected from the attribute dropdown menu. The available styles for routing are:
| Example | Style |
|---|---|
| Normal |
| Dashed |
| DashedDotLine |
| DashedDotLine2 |
| FlexibleHose |
| HatchedAreaLarge |
| HatchedAreaSmall |
| HeatTracing |
| Jacketed |
#### Attribute "Color"
Individual colors can be applied to selected sketch items via the color attribute. The default setting is "By Layer", indicating that the specified PIDSketch color will be applied. The "By Layer" color can be modified individually for each sketch element in the current PIDSketch:
The individual color can be restored to its "By Layer" state by selecting the "Reset color of selected objects" button:
>
### Catalogue
The catalogue contains a collection of custom sketching symbols for IntelliPID sketching. It allows users to add custom P&ID sketching symbols to IntelliPID, enabling users to extend the sketching abilities and adapt sketching fully to their needs.
When loading a model, UDiTH checks for a upvintellipidsketchitems.txt file located in the \Data\ folder of the model. This file contains the linkage to all available items for the current model.
For more details about the sketch items list file and how to add your own custom symbols, see section [**Sketch item index file**](#sketch-item-index-file) in the chapter [**Custom settings**](#custom-settings-files).
### Labels
In the tab labels, users can select predefined labels and place them on the sketching objects. The attributes of the label are inherited by the sketching objects. These label attributes can be directly modified either on the sketch item itself or on the label.
The labels can be predefined in the **IntelliPIDattributes.xlsx** in the tab "LabelDefinition". Please see the chapter [**Worksheet "LabelDefinition**](#worksheet-labeldefinition).
### Sketch Items
In the tab sketch items all the existing sketch elements on the current PIDSketch are listed and can be also selected.
## P&ID comment
|
| Create a comment for the currently selected P&ID object. The comment will attach to the centre of the object with a leader line. The leader line can be shown or hidden respectively – for further details, see section [**Context buttons**](#context-buttons) in the chapter [**Files panel**](#files-panel). |
The report creation dialogue shows a list of predefined reports. These are defined in the Excel file `IntelliPidReportDefinition.xlsx`.
For more details about predefined reports, see [**Report definitions**](#report-definitions) in the chapter [**Custom settings**](#custom-settings).
Selecting a report definition opens the report results page, where additional filters can then be applied.
Two buttons are shown next to each report definition:
| **Report Settings** – Opens the Report Editor and allows you to modify the predefined report definition. For more details, see [**Report editor**](#report-editor) below. |
|
| **Save Report** – Opens the save dialogue directly. You can save the report result as an `.xlsx` or `.csv` file for further use outside UDiTH. |
- The **Reset** button clears the **Selected attributes** table. All other settings remain unchanged.
- Clicking **OK** generates the report and displays the **Report Results** view.
### Report Results
The report results are displayed in the **Report Results** screen. The screen is divided into the **Report Menu** on the left and the results grouped by attributes.
You can select multiple results by holding down the **Ctrl** key while clicking the lines:
#### Report Menu
The report menu contains functions that help you narrow down the results, locate items on the P&ID, or export the results:
|
| **Reload Report** – Updates the report, for example if custom attributes have changed. |
|
| **View in model** – Highlights the selected items in the corresponding P&IDs. If the P&IDs are not already open, they are opened automatically and shown in the tab bar. |
| **Select underlying objects** – This function currently provides the same result as **View in model**. |
|
| **Copy current report definition** – Copies the current report definition to the clipboard so that it can be saved in the report definition file. For more details, see [**Report definitions**](#report-definitions) in [**Custom settings**](#custom-settings). |
|
| **Customise Report Settings** – Opens the Report Editor and allows you to modify the current report definition. For more details, see [**Report editor**](#report-editor). |
|
| **Save Report** – Opens the save dialogue directly. You can save the report result as an `.xlsx` or `.csv` file for further use outside UDiTH. The button is available via the save options in the right panel. |
|
**Toggle quick filter** – Toggles the quick filter to narrow down report results.
When activated, another line is shown below the attribute names. Wildcards can be used:
The line consists of a filter string field and two additional buttons:
 **Hide/show exclusive clauses** – Allows additional filters to be set for showing or hiding exactly defined values, and shows the current number of values set.
 **Clear filter** – Clears and resets all filters.
|
| **Filter combine mode** – If several filters are set, they are combined with an **OR** operator by default, which means that only one filter condition must be true. If you switch to **AND**, all filter conditions must be fulfilled for the item to be listed. |
All lines with the corresponding values are then either shown or hidden in the results list.
#### Custom Attribute Editing
If multiple lines are selected and a custom attribute with a CodeList is included in the report, it can be changed in bulk for all selected items:
|
|
> *There is a limit of about 20 elements per row. The number of elements can be checked by adding a special attribute "count" in the report editor. For even more detailed reporting and advanced reporting features, use CAXperts [UniversalReporter](https://www.caxperts.com/universalreporter/).*
## Custom Settings
UDiTH uses a range of files that can be used to customise the content and options available in the software itself.
The following sections describe the different file types.
### Autostart Files
UDiTH automatically considers several default and settings files during start-up.
For this to work, the files must be named exactly as shown in the list below:
| Location | Name | Function |
|---|---|---|
| .\\Data\\ | intelliPidLinks.xlsx | Linking file for external links and documents. |
| .\\Data\\ | intelliPidAttributes.xlsx | Definition of custom attributes to be used in IntelliPID. |
| .\\Data\\ | intelliPidAttributeData.xlsx | Custom attribute values for IntelliPID to be loaded on UDiTH startup. |
| .\\Data\\ | intelliPidReportDefinition.xlsx | Definition of reports and their filters for IntelliPID. |
| .\\Data\\colorfiles\\ | upvcolorindex.txt | Listing of the default display styles to be listed in the Display Style Selection in the UDiTH [**Load display style**](#display-styles) menu. |
| .\\Data\\ | upvintellipidsketchitemindex.txt | Lists all catalogue items to be shown in IntelliPID Sketching. |
**Link** – The link can be a web link to a website or web-based database with the required link structure, an absolute path, or a path relative to the model's root directory, which is the directory containing the `Data` folder.
**Condition** – The condition can be any filter, including wildcards, that relates to an attribute in UDiTH.
**Name** – The name is the display name of the link. This is the text shown in the Attributes panel in UDiTH.
**Color** – The colour setting can be either a hexadecimal RGB colour definition preceded by **#**, or one of the Excel default colour names: **black, white, red, green, blue, yellow, magenta, and cyan**.
### Custom Attributes
Custom attributes are user defined attributes that can be altered before each launch of UDiTH. Their values can be changed at runtime (except calculation attributes).
The Custom Attributes for IntelliPID are defined in the file **IntelliPidAttributes.xlsx**
This file can contain six worksheets (tabs):
- **Definition**
- **Codelist**
- **Filter**
- **Meta**
- **SketchDefinition**
- **LabelDefinition**
#### Worksheet "Definition"
In this worksheet, the custom attributes are defined:
**Id** – The Id of the custom attribute can be any number. The only condition is that an Id must be unique throughout the complete custom attributes list. This Id is later used for value assignment.
**Name** – The displayed name of the attribute in UDiTH.
**SourceAttribute** – The attribute the custom attribute "attaches" itself to. E.g., SP_ID generates many entries since it attaches itself to any object with the attribute SP_ID.
This may influence the performance of UDiTH. It is highly recommended to use "SourceAttribute" as specific as possible.
**Filter** – Sets a filter to assign the custom attributes only to objects covered by the filter. A filter can be directly entered here (row 5), wildcards are valid. Instead, a predefined filter can be set (worksheet "Filter").
> *Please note that filters are applied sequentially. When the same filter is run several times in a definition, the according query will be executed several times. This can influence performance negatively. Instead, use predefined filters*.
**DataType** – The data type defines which properties an attribute will have. There are three basic types:
- **Calculation** – Defines a value that will be calculated on UDiTH launch. This is the only custom attribute that cannot be altered during runtime. For IntelliPID, only the calculation HasLink is available (DefaultValue "ThreeD" is mandatory) that gives back a Boolean if the object exists in 3D.
- **Freetext** – Defines a freely editable text attribute during runtime. Accepts all value strings.
- **Codelist** – Defines a codelist attribute. In UDiTH, these attributes are displayed as a combo box, enabling you to choose from a predefined codelist of values -- see worksheet "Codelist".
**DefaultValue** -- The value that will be assigned to the custom attribute automatically without any manual assignment being necessary. Depending on the DataType, there are different options available:
- **For Calculation** – Only DefaultValue "ThreeD" is available.
- **For Freetext** – can be left blank or contain any string.
- **For Codelist** – The default value should be a value listed in the codelist definition.
**Parameter1** – This parameter gives additional parameters, depending on the DataType of the attribute:
- **For Calculation** – Only parameter "HasLink" is available.
- **For Freetext** – not used
- **For Codelist** – The name of the codelist to use, see worksheet "Codelist"
**Id** – The Id of the custom attribute can be any number. The only condition is that an Id must be unique throughout the complete custom attributes list. This Id is later used for value assignment.
#### Worksheet "Codelist"
In this worksheet, the codelists for the custom attributes are defined:
- **Name** – The name of the codelist. This is the Name used in Parameter1 on worksheet "Definition"
- **Value** – defines all values available for the codelist in column A (Name)
- **Color** – defines the color the respective value will be shown in in UDiTH. This also affects the color used in the legend. It can be either a hexadecimal RGB color definition preceded by a **\#** or one of the Excel default colors in clear name notation: **black, white, red, green, blue, yellow, magenta, and cyan**.
- **Line_Width_Factor** – modifies the line width of the P&ID objects by a factor. Factor 1 means no change to the line width.
- **MarkUp** – allows line highlighting of the P&ID objects. Transparency is controlled by the last two digits in the “Color” column and the width factor by the digit in the "Line_Width_Factor" column.
#### Worksheet "Filter"
In this worksheet, often used filters for the custom attribute definition can be set:
Filters entered in the worksheet "Definition" are always executed separately, even if the contents of the filter strings are identical. This can slow down the loading of the custom attributes on UDiTH launch.
Instead, you can use the worksheet "Filter" to define a referenced filter. Filters defined here are run only once, no matter how often they are invoked on the worksheet "Definition". Whereas a direct filter runs every single time it is invoked, using the predefined filter reuses the result of the filter, thus increasing the performance of custom attributes loading.
- **Name** – The unique name of the filter to be used as reference in the tab "Definition". This name can be freely assigned.
- **Filter** – The actual filter string. Wildcards are allowed.
#### Worksheet "Meta"
In this worksheet, the parameters for the mailing of custom attribute changes can be defined:
For IntelliPID, there are two keys available:
- **WorkcardMail_To** – the recipient or list of recipients for the list of custom attribute changes.
- **WorkcardMail_Subject** – the subject automatically added to the mail generated.
#### Worksheet "SketchDefinition"
In this worksheet, the changeable or read-only attributes can be defined for sketch items:
- **Name** – The name of the attribute to be displayed on a sketch item.
- **Filter** – The name of the predefined filter from the worksheet "Filter". When a filter is set, the attributes will be applied to the sketch items defined in it.
- **DataType, DefaultValue, Parameter1** – Please refer to the description in the chapter [**Worksheet "Definition**](#worksheet-definition).
- **ReadOnly** – True: attribute is read-only. False: attribute is changeable during runtime.
#### Worksheet "LabelDefinition"
This worksheet allows admins to predefine different labels for sketch items. Labels can contain multiple entries, such as pipeline number. The order of the individual strings of one label corresponds to the order in the Excel rows:
- **Label_Name** – The displayed label name in the PIDSketch tab "Labels".
- **Entry_Type** – Attribute: The entry will be treated as an attribute with a changeable value. Codelist: The entry will be treated as a codelist attribute. Const: A fixed entry in the label string.
- **Entry_Name** – Attribute: The name for the displayed attribute. Codelist: The name for the codelist defined in the worksheet "Codelist". Const: Fixed text entry or line break operator "\
" to create a multi-line label.
- **Default_Value** – Attribute, Codelist: The default value for the displayed attribute.
- **Font** – Specifies the system font to be used for the label.
- **Font_Size** – Specifies the font size to be used for the label.
### Report definitions
To define a report that will be listed in the report selection list, the file IntelliPidReportDefinition.xlsx is used. There are two ways to create a new report definition:
#### Definition by copy
Create a new report and in the **Report Results** screen use the **Copy current report definition** function. This will copy the current report definition to the clipboard.
Then paste the content of the clipboard to the next free row in the report definition file.
#### Manual definition
You can also create a report definition manually by editing the report definition file directly:
There are the following fields used to define a custom report. The fields highlighted are optional fields. They can stay empty without any impact on the functionality:
- **Name** – The name of the codelist. This is the Name used in Parameter1 on worksheet "Definition".
- **Forbidden** (optional) – define actions you wish to block for the report: **C** (customize), **F** (filter), or **S** (save).
You can also combine these restrictions with comma or semicolon. Example: **C,F;S**
- **Description** (optional) – Additional description to explain the purpose of the report.
- **Sort Column** – Defines the column by which the report will be sorted. If no prefix is added, the report will be sorted in ascending order.
Optionally, you can add a prefix **ascending:** or **descending:** before the attribute.
- **Filter** (optional) – All attributes, including custom attributes as well as wildcards can be used for filtering.
- **Scope** (optional) – Defines the scope of P&IDs. Options are **All**, **All Open**, **CurrentDrawing**, and **Selected**.
- **Attributes** – Attributes to be included in the report. For every additional attribute, add an entry to the first free column to the right.
The number of attributes to be reported on is not limited.
There are two additional special attributes for reporting: **Color** returns the current color of the object and **Count** gives you the number of objects contained in that object. For instance, a vessel with 4 nozzles will have a count of 5.
### Display styles
#### Color list file
UDiTH uses one central list file (upvcolorindex.txt) for the listing of available Display Styles. This file is located in the **colorfiles** folder of your model's **Data** folder.
It is automatically considered on launch. It contains the names of the color files to be show by default in the **Select display style** selection in the [**File panel**](#files-panel).
#### Color Files
You can create custom color files using Excel for the definition of colors, conditions and color groups.
**Color** – defines colors to colorize the designated items. There are two ways to define a color:
- Use Excel colors in clear name notation: **black, white, red, green, blue, yellow, magenta, and cyan**.
- Use HTML (hexadecimal) color codes starting with \# followed by 6 digits for the basic colors plus two optional digits for opacity: **#RRGGBBOO**.
Please note that the hexadecimal values range from 00 (decimal 0) to FF (decimal 255).
**Aspect** is an option for 3D coloring and is not used for IntelliPID display styles.
For **Condition** user can enter a filter for any attribute or custom attribute. Wildcards are supported.
**GroupName** is an optional value by which you can define separate color groups in one file. This enables you to define several different conditions without the need to define separate color files.
Conditions belonging to the same color group must have the exact same group name.
**Legend_text** – defines the descriptive text displayed next to the corresponding color in the legend.
**Legend_display** – controls whether the legend text is shown or hidden when the legend is displayed.
**Line_Width_Factor** – modifies the line width of the P&ID objects by a factor. Factor 1 means no change to the line width.
**MarkUp** – allows line highlighting of the P&ID objects. Transparency is controlled by the last two digits in the “Color” column and the width factor by the digit in the "Line_Width_Factor" column.
### Sketch item index file
To use custom sketching items, a sketch item index file has to be created and named **upvintellipidsketchitemindex.txt**. This file contains the paths to the according custom symbol files you wish to be included in your model.
A catalog item consists of a pair of files: an .svg file that defines the graphics of the symbol itself and a .png file that delivers the symbol preview to be shown in the catalog. A sample IntelliPID Sketch catalog can be downloaded [**here**](https://downloads.caxperts.com/#udith_sampledata). It includes process and signal line symbols, as well as off-page connector symbols.
The .svg custom symbols (Scalable Vector Graphics) can be created using either a variety of desktop software, web-based apps, and code editors or using SmartSketch and converting the .sym symbols using **AdapterForSpid**.
IntelliPID recognizes the special flags stored in symbol.svg. These flags must be added manually to the SVG code. If converting SmartSketch symbols via AdapterForSpid, the flags can be entered directly into the configuration file.
#### Available parameters
Svg general specification:
| Flag | Function |
|---|---|
| DrawingFactor="3780" | Fix entry for correct rendering of the symbol in IntelliPID. |
| Inkscape="1.4" | Fix entry for correct rendering of the symbol in IntelliPID. |
| SymbolOriginX="0.5" | Symbol's origin in x-axis. For symmetric symbol "0.5" means the mid-point of the symbols in x-axis. |
| SymbolOriginY="0.5" | Symbol's origin in y-axis. For symmetric symbol "0.5" means the mid-point of the symbols in y-axis. |
| ShowLine="1" | Symbol can be added to the routing without interrupting the line, e.g. insulation symbol. |
| KeepColor="1" | Symbol will keep its original color, independent of the PIDSketch Layer color. |
| Linestyle="1" | This parameter is used to create different routing patterns. |
| DoNotAllowAddObject="1" | This parameter works in conjunction with the "linestyle" flag. It determines whether a symbol can be added to the routing or not. |
| *Parameters for symbols with a leader line:* | |
| LeaderX="0.5" | Specifies the relative x-coordinate for start point of leader line vector. |
| LeaderY="0.5" | Specifies the relative y-coordinate for start point of leader line vector. |
| LeaderVectorX="0.15" | Specifies the relative x-coordinate for end point of initial leader line vector. |
| LeaderVectorY="-0.40" | Specifies the relative y-coordinate for end point of initial leader line vector. |
| LeaderSymbol="Path_to_Symbol" | It creates a combined symbol. It leads to a reference symbol that will be attached to the end of the leader line. For example, in the case of shutdown planning, you would add a mark to the valve together with the description. |
| Flag | Function |
|---|---|
| type ="start" | symbol for the start terminator of the line. |
| type ="end" | symbol for the end terminator of the line. |
| type ="auxiliary" | flag for an auxiliary line (e.g. heat tracing). |
| Flag | Function |
|---|---|
| attribute="Your Text" | It flags text that should be used as an attribute within a custom IntelliPID symbol and made visible on the symbol. |
| attribute="Opc_opctag" | It adds a special tag that can connect existing OPCs and sketch OPCs and make it visible on the symbol. This tag is added automatically when the symbol contains "*opc*" in the name. |
).
## Create a Link File
Link files are created in Excel. The file should contain the following columns:
| Condition | Link | Name |
|---|---|---|
| Task=Piping | https://www.caxperts.com/ | Homepage |
| Task=Structure | https://en.wikipedia.org/wiki/Structure | Wikipedia |
Because drawings are rendered in PDF format, you can zoom in without any loss of quality.
You can also generate a double-sided ISO PDF and preview the 3D objects to be included.
> Links to objects in the 3D model are not retained.
## Deep Linking without UDiTH Portal
> If you use UDiTH Portal, use a [model link](/UDiTH%20Portal/Linking) instead. The Portal generates and manages these URLs for you, and the link stays valid when a new model version is published. The manual approach described below applies when no Portal is available.
You can use deep links in documents such as Word files, websites, and emails to open UDiTH and execute specific queries and commands.
Deep linking uses the URL handler `upvapi://`.
**Structure:**
`upvapi://| A | B | C | |
|---|---|---|---|
| 1 | Model URL | ... | - |
| 2 | Attribute | Value | Commands |
| 3 | Name | D-100 | CMD!Fit |
| 4 | Task | Piping | CMD!SetVisibility=false |
| 5 | Pipeline | S-1672 | CMD!Select&CMD!IntelliClip=1 |
| 6 | Task | \* | CMD!SetCameraView=3037!2476!72!180!180!10 |
| 7 | ... |
| Command | Description |
|---|---|
| ClearClipping | Disables clipping. |
| ClearColor | Restores the original object colours. |
| ClearCustomAttributes | Resets all changes made to custom attributes during the current session. |
| ClearHighlight | Disables highlighting. |
| ClearLinks | Removes links loaded from link files. |
| ClearSelection | Clears the current selection. |
| Color | `Color=[HTML colour code]` using the format `#RRGGBB` or `#RRGGBBAA`. **Example:** `CMD!Color=#FF0000` |
| Combine | `Combine=[OR/AND]` uses `OR` between query conditions instead of `AND`, which is the default. |
| ExportPackageFile | Exports package files to the specified path. |
| Fit | Optional parameter: `Centred`. `true` (default): fits to the centre of the box. `false`: fits to the screen borders of the current view. **Example:** `CMD!Fit=true` |
| FocusViewer | Brings the UDiTH window to the foreground and gives it the input focus. This command only has an effect on a local model. |
| Highlight | Highlights the specified object. **Example:** `Name=D-100&CMD!Highlight` |
| IntelliClip | `IntelliClip=[distance in metres]` Values `> 0` display only the object. `0` also displays objects touching the selected object. Decimal values are supported. |
| LoadColorFile | `LoadColorFile=[online or offline location]` Local: `CMD!LoadColorFile=C:\colors.xlsx` Via HTTP: `CMD!LoadColorFile=http://example.com/colors.xlsx` Via UNC: `CMD!LoadColorFile=file://////server/share/colors.xlsx` Note: for UNC paths, it is important to use six slashes (`//////`) after `file`. **Examples:** `CMD!LoadColorFile=c:\colors.xlsx` `CMD!LoadColorFile=http://demo.universalplantviewer.com/demoPlant/4/0/colors.xlsx` |
| LoadConfigFile | Loads a configuration file. Parameters: - configuration file name - combine mode (optional) By default, existing settings are cleared. `Merge` keeps existing views and merges them, overriding existing values with those from the configuration file. **Example:** `C:/config.upv!Merge` |
| LoadLinkFile | `LoadLinkFile=[online or offline location]` Local: `CMD!LoadLinkFile=C:\links.xlsx` Via HTTP: `CMD!LoadLinkFile=http://example.com/links.xlsx` Via UNC: `CMD!LoadLinkFile=file://////server/share/links.xlsx` Note: for UNC paths, it is important to use six slashes (`//////`) after `file`. |
| LoadPackageFile | Loads package files from the specified path. Parameters: Parameters: - URL - `Replace` (optional). If set to `true`, current packages are replaced instead of being added to the existing ones. **Example:** `CMD!LoadPackageFile=c:\package.upvf!true` |
| LoadSketch | Loads a sketch from the specified path. A second parameter can be used to rename the sketch. **Example:** `CMD!LoadSketch=C:\Sketch\SketchFile.upvsk!NewName` |
| ResetView | Resets the camera mode, camera position, rotation, and states such as highlighting to the state used when the model was loaded. |
| SearchFallback | This command automatically adds the search string to the search box. If the exact search returns no results, a fuzzy search is started automatically. **Example:** `upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=E240&NozzleName=N8&CMD!Select&CMD!Fit&CMD!Searchfallback` This starts a search and finds Nozzle N8 on equipment E-240. |
| Select | Selects the specified object. **Example:** `Name=D-100&CMD!Select` |
| SetCameraView | `SetCameraView=[X!Y!Z!rotationX!rotationY!rotationZ]` using Euler angles. **Example:** `CMD!SetCameraView=3037!2476!72!180!180!90` sets the camera to coordinates `3037` (X), `2476` (Y), and `72` (Z = height), facing parallel to the ground and rotated `90°` to the left. |
| SetCameraViewLookAtTarget | `SetCameraViewLookAtTarget=[X!Y!Z!TargetX!TargetY!TargetZ]` Moves the camera to the specified location and points it towards the target location. |
| SetClippingPlane | Sets the visible camera view distance. The first parameter is the minimum distance for visible objects, and the second is the maximum distance. **Example:** `CMD!SetClippingPlane=20!30` |
| SetStorageVariable | Sets a storage variable. Parameters, in this order: - the key to set - the value - an optional persist flag, `true` or `false`. The default is `false`. Use this command with the LocalStorage Universal API system to send a message to a running AppControl. **Example:** `CMD!SetStorageVariable=MyKey!MyValue` |
| SetTreeConfiguration | `SetTreeConfiguration=[discipline!discipline...]` **Example:** `CMD!SetTreeConfiguration=Task!SystemPath` |
| SetVisibility | `SetVisibility=[True/False]` |
| SetVisibleAspects | `SetVisibleAspects=[aspect!aspect]` **Example:** `CMD!SetVisibleAspects=Simple Physical!Insulation` shows both insulation and simple physical. |
| ShowOnly | Sets all query objects to visible and hides all other objects. |
| ShowMessage | Shows a message and title in a message box. **Example:** `CMD!ShowMessage=Your Message!Your Title` |
| TakeAndSaveScreenshot | Takes a screenshot using the following parameters, in this order: - path where the image is to be stored - width in pixels - height in pixels - field of view in degrees (`> 160` may produce incorrect images) - format, either `.png` or `.jpg` - hide UI, `true` or `false` - enable anti-aliasing, `true` or `false` - enable transparent background, `true` or `false` - model in best quality, `true` or `false` **Example:** `CMD!TakeAndSaveScreenshot=C:\Test\image.jpg!2000!1500!120!png!true!true!true!false` |
| VolumeClip | `VolumeClip=[distance in metres]` Values `< 0` are treated as `0`. Decimal values are supported. |
| VolumeClipByCoordinates | Runs the volume clip algorithm using a bounding box defined by the following parameters: - X min - Y min - Z min - X max - Y max - Z max **Example:** `CMD!VolumeClipByCoordinates=-10.0!-10.0!-10.0!20.0!20.0!20.0` |
| Icon | Key | Description |
|---|---|---|
|
| SettingsButton | Hide the **Settings** button. |
|
| TreeToggleButton | Hide the **nTreeToggleButton** button. |
|
| ProjectTreeConfigurationButton | Hide the **Configure the project tree** button. |
|
| FilesTreeAddButton | Hide **Add File** button. |
**Link** - The link can be a web link to a website or web-based database with the required link structure, an absolute path, or a path relative to the model's root directory, which is the directory that contains the `Data` folder.
**Condition** - The condition can be any filter, including wildcards, that relates to an attribute in UDiTH.
**Name** - The name is the display name of the link. This is the text shown in the Attributes panel in UDiTH.
**Colour** - The colour setting can be either a hexadecimal RGB colour definition preceded by a **\#** or one of the Excel default colours in
clear name notation: **black, white, red, green, blue, yellow, magenta, and cyan**.
## Custom Attributes
Custom attributes are user-defined attributes that can be changed before each launch of UDiTH. Their values can also be changed at runtime, except for calculation attributes. The custom attributes for IntelliPID are defined in `intelliPidAttributes.xlsx`. This file can contain four worksheets (tabs):
- **Definition**
- **Codelist**
- **Filter**
- **Meta**
### Worksheet "Definition"
This worksheet defines the custom attributes.
**Id** -- The ID of the custom attribute can be any number. The only requirement is that each ID must be unique throughout the full list of custom attributes. This ID is later used for value assignment.
**Name** -- The name under which the attribute is displayed in UDiTH.
**SourceAttribute** -- The attribute to which the custom attribute attaches itself. For example, `SP_ID` can generate many entries because it attaches itself to every object with the attribute `SP_ID`. This can affect UDiTH performance.
It is strongly recommended to define `SourceAttribute` as specifically as possible.
**Filter** -- Sets a filter so that custom attributes are assigned only to objects covered by that filter. A filter can be entered directly here, and wildcards are supported. Alternatively, a predefined filter can be used from the `Filter` worksheet.
> Filters are applied sequentially. Consider using predefined filters instead. When the same filter is used several times in a definition, the corresponding query is executed several times, which can reduce performance.
**DataType** -- The data type defines which properties an attribute has. There are three basic types:
- **Calculation** -- Defines a value that is calculated when UDiTH starts. This is the only type of custom attribute that cannot be changed at runtime. In IntelliPID, only the `HasLink` calculation is available. `DefaultValue="ThreeD"` is mandatory, and the result is a Boolean value that indicates whether the object exists in 3D.
- **Freetext** -- Defines a freely editable text attribute that can be changed at runtime. All value strings are accepted.
- **Codelist** -- Defines a codelist attribute. In UDiTH, these attributes are displayed as a combo box, allowing you to choose from a predefined list of values. See the `Codelist` worksheet.
**DefaultValue** -- The value that is assigned automatically to the custom attribute without any manual input.
Depending on the `DataType`, different options are available:
- **For Calculation** -- Only `DefaultValue="ThreeD"` is available.
- **For Freetext** -- Can be left blank or contain any string.
- **For Codelist** -- The default value should be one of the values listed in the codelist definition.
**Parameter1** -- This field provides additional parameters depending on the `DataType` of the attribute:
- **For Calculation** -- Only the parameter `HasLink` is available.
- **For Freetext** -- Not used.
- **For Codelist** -- The name of the codelist to use. See the `Codelist` worksheet.
The `Id` field must remain unique throughout the complete custom attributes list.
### Worksheet "Codelist"
This worksheet defines the codelists for custom attributes.
**Name** -- The name of the codelist. This is the same name used in `Parameter1` on the `Definition` worksheet.
**Value** -- Defines all values available for the codelist under the corresponding name.
**Colour** -- Defines the colour in which the respective value is shown in UDiTH. This also affects the colour used in the legend. It can be either a hexadecimal RGB colour definition preceded by `#`, or one of the Excel default colour names: **black, white, red, green, blue, yellow, magenta, and cyan**.
### Worksheet "Filter"
This worksheet is used to define frequently used filters for custom attributes.
Filters entered directly in the `Definition` worksheet are always executed separately, even if the filter strings are identical.
This can slow down the loading of custom attributes when UDiTH starts.
Instead, you can use the `Filter` worksheet to define a referenced filter. Filters defined here are executed only once, no matter how often they are referenced from the `Definition` worksheet. A direct filter runs every time it is used, whereas a predefined filter reuses the result and therefore improves performance when loading custom attributes.
**Name** -- The unique name of the filter to be used as a reference. This name can be chosen freely.
**Filter** -- The actual filter string, as described in the `Definition` worksheet. Wildcards are supported.
### Worksheet "Meta"
This worksheet defines the parameters used for emailing custom attribute changes.
For IntelliPID, two keys are available:
- **WorkcardMail_To** -- The recipient or list of recipients for the list of custom attribute changes.
- **WorkcardMail_Subject** -- The subject that is added automatically to the generated email.
## Report Definitions
To define a report that appears in the report selection list, use the file `intelliPidReportDefinition.xlsx`. There are two ways to create a new report definition:
### Definition by Copy
Create a new report and use **Copy current report definition** in the **Report Results** screen. This copies the current report definition to the clipboard. You can then paste the clipboard contents into the next free row of the report definition file.
### Manual Definition
You can also create a report definition manually by editing the report definition file directly:
The following fields are used to define a custom report. The highlighted fields are optional and can be left empty without affecting functionality:
**Name** -- The name of the report.
**Forbidden** (optional) -- define actions you wish to block for the report: **C** (customise), **F** (filter), or **S** (save).
You can also combine these restrictions with comma or semicolon.
Example: **C,F;S**
**Description** (optional) -- An additional description explaining the purpose of the report.
**Sort Column** -- Defines the column by which the report is sorted. If no prefix is added, the report is sorted in ascending order. Optionally, you can add the prefix `ascending:` or `descending:` before the attribute.
**Filter** (optional) -- All attributes, including custom attributes as well as wildcards can be used for filtering.
**Scope** (optional) -- Defines the scope of the P&IDs. Options are **All**, **All Open**, **CurrentDrawing**, and **Selected**.
**Attributes** -- The attributes to be included in the report. For each additional attribute, add an entry in the next free column to the right. The number of attributes is not limited.
There are two additional special attributes for reporting: **Colour** returns the current colour of the object, and **Count** returns the number of objects contained within that object. For example, a vessel with four nozzles has a count of five.
## Display Styles
### Colour List File
UDiTH uses one central list file, `upvcolorindex.txt`, to define the available display styles. This file is located in the **colourfiles** folder within your model's **Data** folder. It is loaded automatically when UDiTH starts. It contains the names of the colour files that are shown by default in the **Set display style** selection in the **File menu**.
### Colour Files
You can create custom colour files in Excel to define colours, conditions, and colour groups.
**Colour** -- Defines the colours used to colourise the designated items. There are two ways to define a colour:
- Use Excel colours in clear name notation: **black, white, red, green, blue, yellow, magenta, and cyan**.
- Use HTML (hexadecimal) colour codes starting with \# followed by 6 digits for the basic colours plus two optional digits for opacity:
**\#RRGGBBOO**. Please note that the hexadecimal values range from 00 (decimal 0) to FF (decimal 255).
For **Condition**, you can enter a filter for any attribute or custom attribute. Wildcards are supported.
**Aspect** is an option for 3D colouring and is not used for IntelliPID display styles.
**GroupName** is an optional value that allows you to define separate colour groups within one file. This lets you define several different conditions without needing separate colour files. Conditions that belong to the same colour group must use exactly the same group name.
## Sketch Item Index File
To use custom sketching items, you must create a Sketch Item index file named `upvintellipidsketchitemindex.txt`. This file contains the paths to the Sketch Item files that you want to include in your model.
A catalogue item consists of a pair of files: an `.svg` file, which defines the graphics of the symbol itself, and a `.jpg` or `.png` file, which provides the preview shown in the catalogue.
### Adding Objects to the Catalogue
You can add any `.svg` file, together with an optional corresponding `.jpg` or `.png` file, to your catalogue. UDiTH loads it when the model starts if the object is valid and correctly listed, with name and path, in the Sketch Item index file. You can use absolute paths, relative paths, and includes:
**Absolute path** - `C:\temp\Pumps\pump2.svg`
**Relative path** -- `IntelliPidCatalogue\Valves\valve1.svg` (relative to the location of your UDiTH model folder)
**Include** - `#include D:\yourindex.txt` - Include can be used to manage objects for the whole company across as many files as required, rather than adding individual objects to individual models. In this example, `yourindex.txt` refers to a separate Sketch Item index file.
## Deep Linking in IntelliPID
You can include deep links in any document type that supports links, such as Word files, websites, or emails, to open UDiTH and transfer a combination of queries and commands.
Deep linking uses the URL handler `upvapi://`.
**Structure:**
`upvapi://| Condition | Link | Name |
|---|---|---|
| Task=Piping | https://www.caxperts.com/ | Homepage |
| Task=Structure | https://en.wikipedia.org/wiki/Structure | Wikipedia |
|
| After clicking **Create a report** in **File management**, you can choose a report definition file or create a new report. Report definition files are Excel files that must be stored in the `Data` folder of your UDiTH directory. By default, saved reports follow this naming convention: |
A report definition file can contain the following columns:
| Name | A descriptive name for your report. |
| Description (optional) | Additional description explaining the purpose of the report. |
| Filter (optional) | You can use all attributes including custom attributes. |
| Scope (optional) | Choose "All", "Selected" or "Visible". |
| Column (optional) | The attribute column that should be used for sorting your report. |
| Sort (optional) | You can sort in **ascending (asc)** or **descending (des)** order. If no sorting order is specified, UDiTH sorts in ascending order. Example: `descending:Name` |
| Forbidden (optional) | Enter actions that you do not want to allow for your reports: **C** (customise), **F** (filter), **S** (save). Combine them using a comma or semicolon. Example: `C,F;S` |
| Attributes | The attributes that the report should contain. **Colour** returns the current colour, and **Count** returns the number of objects contained within that object. For example, a vessel with four nozzles has a count of five. |
| Command | Description |
|---|---|
| model | Path or URL of the model to load at start-up. |
| forcenewinstance | Forces the creation of a new instance, even when the same model is already loaded. |
| forceapicall | Prevents the creation of a new process and only attempts to send the API command. |
| apitcpport | The TCP port used by the API. |
| silent | Hides the splash screen at start-up. |
| nocrashmessage | Hides the message shown in the event of an unexpected crash. |
| softwarerenderer | Uses the software renderer. |
| hwnd | Renders into a window identified by an `HWND`. |
## 3D Toolbar
### Display and Hide 3D Toolbar
- Click the 3D model with the **Hand** tool to display the 3D toolbar.
The 3D toolbar always appears above the upper-left corner of the 3D model and cannot be moved.
- Hide the toolbar by right-clicking the 3D model and choosing **Hide toolbar**. To show the toolbar again, choose **Show toolbar** from the same context menu.
- You can expand and collapse the 3D tools shown on the toolbar by using **Tools → Expand/Collapse 3D tools** in the context menu.
> All tools that can be used from the 3D toolbar can also be used by right-clicking the 3D model and using the different items of the context menu.
## Use 3D Navigation Tools
- **Rotate (
):**
Turns 3D objects relative to the screen. How the objects move depends on the starting view, where you begin dragging, and the direction in which you drag, for example in a straight line, a curve, a circle, or a loop.
> You can also use the **Hand** tool to select an object if **Enable selection for the hand tool** is selected in the 3D preferences.
- **Spin (
):**
Rotates a 3D model in parallel with two fixed axes in the 3D model, the x-axis and the z-axis.
- **Pan (
):**
Moves the model vertically and horizontally only. You can also pan with the **Hand** tool by pressing **Ctrl** while dragging.
- **Zoom (
):**
Moves you towards or away from objects in the scene when you drag vertically. You can also zoom with the **Hand** tool by holding down **Shift** while dragging.
- **Walk (
):**
> The **Walk** tool is only available when you select the 3D Preferences setting that consolidates tools or when you right-click the 3D model and choose **Tools** → **Walk**.
Pivots horizontally around the scene when you drag horizontally, moves forwards or backwards through the scene when you drag vertically, and maintains a constant elevation level regardless of how you drag. The **Walk** tool is especially useful for architectural 3D models.
- Drag with the right mouse button to change how several of the 3D navigation tools behave:
For the **Rotate** and **Spin** tools, right-click dragging temporarily switches to the **Zoom** tool.
For the **Zoom** tool, it behaves like a **Marquee zoom** tool, zooming to the area that you define while dragging.
For the **Walk** tool, right-click dragging makes the tool behave like the **Pan** tool.
### Use 3D Toolbar View Controls
- **Default view** (
):
Returns to a preset zoom, pan, rotation, and projection mode for the 3D model.
> If an object ever moves out of your view, click the **Default view** icon on the 3D toolbar to move the object back into view.
- **Views menu:**
Selects the different views defined for the current 3D model.
- **Toggle model tree (
):**
Opens and hides the model tree.
- **Projection (
):**
Toggles between perspective and orthographic projection of the 3D object.
Orthographic projection effectively removes a dimension, preserving the size ratio between objects but giving the 3D model a less realistic appearance.
- **Model render mode menu (
):**
Selects the different model render modes so that you can see how the 3D shape appears. Compare the differences in rendering speed and quality.
The model rendering modes include combinations of factors that affect the appearance of the 3D object. The illustration below shows a simple tank object rendered in each of the available modes. The default rendering mode is usually **Solid**.
**Table 1: Model rendering modes**
| A. Solid | B. Transparent Bounding Box | C. Transparent |
|---|---|---|
|
|
|
| D. Solid Wireframe | E. Illustration | F. Solid Outline |
|
|
|
| G. Shaded Illustration | H. Bounding Box | I. Transparent Bounding Box Outline |
|
|
|
| J. Wireframe | K. Shaded Wireframe | L. Transparent Wireframe |
|
|
|
| M. Hidden Wireframe | N. Vertices | O. Shaded Vertices |
|
|
|
), (not available in Adobe Reader):**
Shows and hides cross-sections of the object. Click the pop-up button to open the **Cross section properties** dialogue box.
- **Camera properties (
):**
Opens the camera properties window and allows you to modify the camera position. **Save camera view** is not available in **Adobe Reader**.
## Model Tree
### Display and Hide Model Tree
- Open the model tree by clicking the **Toggle model tree** button () on the 3D toolbar, or by right-clicking the 3D model and choosing **Show model tree**.
> You can change the default behaviour of the model tree by right-clicking the 3D model, choosing **3D preferences**, and then selecting an option from the **Open model tree on 3D activation** menu.
The model tree appears in the navigation pane on the left side of the work area.
The model tree has three panes: the Structure pane, the View pane, and the Object Data pane. Each displays a specific type of information or controls.
### Use Structure Pane
The top pane shows the tree structure of the 3D object, which is made up of individual parts. For example, a 3D object showing a storage tank may have separate groups of objects, called nodes, for the tank, insulation, and nozzles.
To configure the model tree and attributes in the PDF file, see the section *3D PDF settings*.
- Move through the hierarchy and see how the related parts in the 3D model are selected when you select the tree nodes.
- Hide various parts, to isolate others, by removing checkmarks next to them.
- Highlight, view, or modify the 3D model content at any level in the model tree by right-clicking a node and selecting the required function.
- Select the **Options** menu and choose any of the following:
> **Model render mode:** Changes the surface appearance of the entire 3D
> model according to the item you choose from the submenu: Transparent
> Bounding Box, Solid, Transparent, Solid Wireframe and so on.
>
> **Show all parts:** Displays the entire 3D model.
>
> **Fit visible:** Displays all visible parts and centres them in the
> view.
>
> **Display bounding box:** Displays the box that encloses the 3D object
> or selected parts of the model.
>
> **Set bounding box colour:** Changes the colour of the bounding box.
> Choose this option, select a colour, and then click OK.
>
> **Hide:** Displays the model without showing the selected parts.
>
> **Isolate:** Displays only the selected part, hiding all others.
>
> **Zoom to part:** Changes the centre focus from the entire 3D model to
> the selected parts. This setting is especially useful for rotating a
> part, allowing the rotation to occur around the part's centre focus
> rather than that of the entire model.
>
> **Transparent:** Displays a see-through version of the selected part.
>
> **Export as XML:** Creates a separate XML file of either whole tree or
> current node of the 3D model.
> The items that appear on the **Options** menu and the order in which they are listed depend on whether the selected 3D model is composed of just one part or multiple parts.
### Use View Pane
The middle pane lists the views that the document author has defined for that 3D object.
- After you changed the view, such as by isolating and rotating a part, simply click one of the listed views to return the 3D model to a saved state.
- Change the default view () in the **3D toolbar** view controls by right-clicking a view in the **View pane** and then choosing **Set as default view**.
### Use Object Data Pane
The lower pane displays other information, including properties and metadata, if any, about the object or part.
- Click a particular object in the 3D view. The Object Data pane is filled in automatically with the properties of the selected object, for example SmartPlant Review properties.
The selected object is highlighted in a bounding box and the attributes are shown on the object data pane:
### Volume Clipping
3D PDF files created by CAXperts **Universal Plant Viewer** contain a volume clipping feature.
- Use the context menu on a 3D object in Acrobat Reader and click **CAXperts - Volume clipping**.
Then enter the volume clipping radius around the selected object:
> All CAXperts menu items use JavaScript. This is not dangerous, so you can ignore the **Warning: JavaScript window** message.
- Finally, press **OK**. Only the selected object and all objects within the specified radius will remain visible.
To switch off volume clipping, click **CAXperts - Reset model** in the context menu.
### Measure with CAXperts - Measuring Tool
- Use the context menu on a 3D object in Acrobat Reader and click **CAXperts - Measuring tool** to measure 3D models.
- Click the first object after this message appears:
- Then click on the second object:
The distance between the centres of the bounding boxes will be shown:
### Link 2D Objects with 3D Objects
The function to link 2D objects with objects of the 3D model is only available in PDF documents created with CAXperts tools.
- Show the 3D model in a floating window by right-clicking the 3D model and choosing **View in floating window**.
- Click a linked item in the 2D drawing to make the 3D window show the item's 3D representation. Links are indicated by the mouse pointer changing to a hand whenever you hover over a link.
## 3D Models in Acrobat Professional
### Measure 3D Objects
- Use the **3D measurement tool** to measure 3D models.
You can create measurements between combinations of points or edges on the 3D model.
- Move the pointer over the 3D model to highlight specific points and edges.
> The **3D measurement tool** supports four types of measurements:
1. perpendicular distance between two straight edges,
2. linear distance between two points,
3. the radius of circular edges, and
4. the angle between two edges (or three points).
You can also display comments while taking measurements. However, these comments, also called measurement mark-ups, are not preserved after the document is closed.
Figure 1: 3D measurement display
1. Click a 3D model in a PDF to enable it.
2. Click the **3D measurement tool** icon
() on the 3D toolbar. (If the 3D
toolbar view is set for consolidated tools, the **3D measurement
tool** is available on the pop-up menu under the **Rotate**,
**Spin**, **Pan**, **Zoom**, or **Walk** tool.)
3. Select the required options in the **Snap enables**, **Measurement types**, and **Units and mark-up settings** areas of the **3D measurement tool** palette.
4. Under **Units and mark-up settings**, change the options as required. Leave the **3D measurement tool** palette open.
5. Measure the 3D model:
- To measure the distance between two positions on the 3D model, click to set a start point and then move the pointer to another location or edge.
- To measure the circumference of a round shape, move the pointer to the edge of the shape so that a circle appears, and click once.
- To create and set the position of an annotation on the measurement, select **Measurement mark-up** in the **3D measurement tool** palette and then type a mark-up message in **Annotation**. Measure the 3D model as described above, but click to set the end point for the measurement and then click a third time to set the location of the measurement and annotation text.
- To discontinue a measurement, right-click and choose **Cancel measurement**.
- To delete a measurement mark-up, click it with the **3D measurement tool** and press **Delete**.
> While measuring, press **Ctrl+Shift** to rotate. Hold down **Ctrl** to pan, hold down **Shift** to zoom, and hold down **Alt** to disable snap.
**Snap enables** options in the **3D measurement tool** palette:
- **3D snap to edge endpoints (****):** Snaps to the entire edge.
- **3D snap to linear edges (****):** Snaps to a straight-line
segment of an edge.
- **3D snap to radial edges (****):** Snaps to a circumference.
- **3D snap to silhouettes (****):** Snaps to the apparent edge of
a part, such as the side of a cylinder.
- **3D snap to planar faces (****):** Snaps to the geometric plane
making up a face of the part.
**Measurement types** options in the **3D measurement tool** palette:
- **3D point to point measurement (****):** Measures the distance between two positions on the 3D model that you click to set a start point and then click another location to set an end point or edge.
- **3D perpendicular dimension (****):** Measures the distance between two edges taken at a right angle to the starting edge.
- **3D radial dimension (****):** Measures the radius at the location clicked.
- **3D angle measurement (****):** Measures the angle between two edges.
**Units and mark-up** options in the **3D measurement tool** palette:
> If you do not see these settings, choose **Show details** on the palette's **Options** menu.
- **Model units scale ratio:** Shows the relationship between units in the model and real object measurements. Use the **Display units** menu to select a different unit for the real object measurements.
- **Measurement mark-up**: Select to have the measurements appear as comments in the PDF.
- **Label:** Type text that you want to appear with the measurement, both in the 3D model area and in the comments panel. (Not available if **Measurement mark-up** is not selected.)
**3D Measurement tool** viewing options
Use the **Options** menu in the **3D measurement tool** palette to set the viewing options.
> The **3D measurement tool** palette changes to the **Distance tool** palette after a brief delay when the pointer moves outside the canvas area of the 3D model. Moving the pointer back over the 3D model restores the **3D measurement tool** options. The **Ortho** option is available only for the **2D Distance**, **Perimeter**, and **Area** tools.
- **Show details:** Shows or hides the **Cursor location** and **Units and mark-up settings** options in the **3D measurement tool** palette.
- **Show rulers:** Shows or hides vertical and horizontal rulers on the page. (Has the same effect as choosing **View** → **Rulers**.)
- **Snap to 2D content;** Ensures precise measurement in 2D objects.
- **Snap to 3D content:** Ensures precise measurement in 3D objects.
- **3D measurement navigation tips:** Opens a dialog box with keyboard shortcuts for several 3D features. You can use these shortcuts while you are measuring.
#### Measuring Preferences
Change the 3D measuring preferences to determine how 3D data is measured. These options appear in the **Measuring (3D)** panel of the **Preferences** dialog box.
> These preferences apply to PDFs that have commenting enabled.
**Use scales and units from model (when present):** Displays measurements based on the model units, if present, taken from the original 3D model. Deselect this option to specify the measurement units manually. This setting can be changed in the **3D measurement tool** palette.
**Use default display unit:** Uses units of measurement that you specify here rather than those in the 3D model.
**Significant digits to display:** Specifies the maximum number of digits in the measurement number.
**3D measuring line colour:** Specifies the colour of the line that appears when you click or drag to measure an object.
**Measure feedback size:** Sets the text size for the measurement display.
**Angular measurements shown in:** Specifies units as either degrees or radians.
**Circular measurements shown as:** Specifies whether the diameter or radius is measured for circular parts.
**3D snap settings:** Turns on snap and specifies whether points, arcs, edges, silhouette edges, or faces are snapped to. Sensitivity indicates how close the pointer needs to be to the item being snapped to. For **Snap hint colour**, specify the colour of the snap line that appears when you hold the pointer over the 3D object.
### Comment on 3D Designs
Comments added to a 3D object are associated with specific views that are defined when the comments are created.
If the view is changed, for example if the 3D object is rotated or moved, the comments are no longer visible.
> Adding comments to 3D model views requires version 7.0.7 or later of **Adobe Acrobat** or **Adobe Reader**.
If you don't want a comment to be associated with a 3D view, add the comment to another part of the page, outside the 3D object area.
#### Add comments to a 3D object
- Select a tool from the **Comment & mark-up** toolbar.
> The text editing tools have no effect on 3D objects.
- Click inside the 3D object area to create a new comment and a new view definition in the model tree with a default name such as `CommentView1`.
To add more comments, do one of the following:
- To create an additional comment in a view, make sure that the required commenting view is selected in the Model Tree, and then click inside the 3D object area.
- To create an additional comment in a new commenting view, make sure that no commenting view is selected in the Model Tree, and then click inside the 3D object area.
> If one of the automatically generated commenting views is deleted, the associated comments are still available. They can be viewed and selected in the Comments panel or in the model tree, where they are listed under **Views**. Selecting a comment switches the 3D model back to the same viewing configuration it had when the comment was added.
#### Display Comments for a 3D Object
Do one of the following:
- In the model tree, select a view that contains comments.
- Click the **Comments** button or choose **View** → **Navigation panels** → **Comments**.
- In the view pane of the model tree, click **Options** and choose **List comments**.
- Double-click a comment to open its comment window.
### Run a JavaScript
If there is a separate JavaScript file associated with the 3D model PDF, you can run it.
- Right-click the 3D model in the PDF, and choose **Run JavaScript**.
## Acrobat 3D Preferences
In the 3D panel of the **Preferences** dialogue box (**Edit** → **Preferences**), you can determine whether the 3D toolbar and model tree are displayed by default. You can also specify a default renderer and decide whether animations are allowed.
**Preferred renderer:** Specifies the rendering engine used and therefore affects both performance and quality, so it is important to select the appropriate renderer. If you select a DirectX or OpenGL option, all rendering takes place using the graphics chip on the video card. If **Software** is selected, rendering may take longer, but performance may be more consistent with that of the model in its original application.
**Enable double-sided rendering:** Some model parts have two sides. To save time and space, you can deselect this option so that only the side facing the user is rendered. If the user looks inside a part rendered with only one side, the back side is invisible.
**Enable hardware rendering for legacy video cards:** Forces the use of a hardware accelerator for even video cards that do not support a pixel shader.
**Open model tree on 3D activation:** Determines whether the model tree is displayed when the 3D model is activated. Choose **Use annotation's setting** to use whichever setting the author selected when adding the 3D model to the PDF.
**Default toolbar state:** Determines whether the 3D toolbar is shown or hidden when a 3D model is activated. Choose **Use annotation's setting** to use whichever setting the author selected when adding the 3D model to the PDF.
**Enable 3D selection for the hand tool:** Lets the user select and highlight parts of the 3D model using the **Hand** tool. If this option is not selected, use the **Object data tool** (**Tools** → **Object data** → **Object data tool**) to select the object.
**Consolidate 3D tools on the 3D toolbar:** Selecting this option places the manipulation and navigation tools under the **Rotate** tool, thereby shortening the 3D toolbar.
**Enable view transitions:** Some 3D models include animated transitions between views. Deselect this option if you want to prevent this 3D animation.
**Optimization scheme for low frame rate:** Specifies what happens to animations of complex models when the frame rate becomes low.
- **None:** Does not compromise the visuals and leaves the frame rate low.
- **Bounding box:** Shows the three-dimensional planes enclosing the parts instead of the parts themselves, which keeps the frame rate high.
- **Drop objects:** Does not show some parts of the model in order to keep the frame rate high.
**Frame rate threshold:** Sets the minimum frame rate, either by dragging the slider or entering a number in the value box. If the frame rate drops below that number of frames per second, the **Optimization scheme for low frame rate** option goes into effect.
---
# UDiTH Capture Station — Introduction
# Introduction
UDiTH Builder uses 2D data, 3D data, and metadata prepared by the following adapters and the SDK to create UDiTH models:
| CAXperts tool | Prerequisite | Converts |
|---|---|---|
| AdapterForSmartReview | Intergraph SmartPlant Review | SmartPlant Review (.vue, .svf), PDS (.dri) |
| AdapterForNavisworks | Autodesk NavisWorks | Autodesk NavisWorks files (.nwc, .nwd, .nwf, etc.) |
| AdapterForE3d | AVEVA PDMS, E3D (.rvm, .att, .txt) | |
| AdapterForIfc | BIM (.ifc) | |
| AdapterForLaserScans | (.obj, .e57, .jpg) | |
| AdapterForDocuments | Intergraph SmartSketch | Intergraph SmartSketch files (.sha) PDMS/E3D Isometrics (.pdf, .hit) PDF files (.pdf) |
| AdapterForDocuments | PDF files (.pdf) | |
| AdapterForSpid | Intergraph SmartPlant P&ID, SmartSketch, Inkscape | Intergraph/Hexagon SmartPlant P&ID |
| AdapterForPdfPid | Inkscape | P&ID (.pdf) |
| SDK | Plugins | Additional data from any source |
The UPVC file is then created.
5. Start Builder.
6. Open the UPVC file that was just created.
7. Click **Generate output**.
8. Select **UDiTH** as the output type.
9. Click **Create**. The UPV model is then created.
10. Open the output folder and start `UDiTH.exe`.
**For mobile devices:**
- Copy the output folder to your web server.
- Download and run the UDiTH app.
- In the app, enter the address of your web server and model.
**For BrowserBasedViewing**
- Open the UPV model website of your organisation directly in your browser.
---
# UDiTH Capture Station — Builder
# Builder
## Introduction
The **Builder** creates UDiTH 3D model data, and PID models, including attributes, project hierarchy, and 2D drawings (ISOs), from various sources using the output of the CAXperts adapters. It can also apply colour files and import Excel data.
The **Builder** cannot be used without the output files created by the adapters. Please refer to the adapter manuals for information on how to create those output files.
> A connection to `20.126.54.190` (`api365.slascone.com`) on port `443` is required. See [Licence upgrade and installation](https://help.caxperts.com/Licensing/Licence%20upgrade%20and%20installation).
## Model creation
This chapter explains how to create a 3D model.
### Input file / folder
Select the browse button to the right of **Input file** and choose one of the file types listed in the following table. To continue, you must select at least one valid file or a folder containing a valid file.
| File ending | Meaning |
|---|---|
| .upvc | A regular UPV database containing 3D objects. |
| .upvm | A merged UPV database created from multiple `.upvc` files. |
After selecting the model files and any additional packages, click **Generate output** in the bottom-right corner of the Builder window to open **Output configuration**.
### Settings
The output folder is the location in which the model is generated.
The colour configuration file can be any `.xlsx` or `.txt` file.
The expiration date prevents the generated output from being used after the specified date.
> Any `.xlsx` file can be selected when browsing for colour files, but only files structured as described in the **Colour Files** chapter of the UDiTH documentation will work as intended.
### UDiTH settings
These settings are available only if the output type is **UDiTH**.
#### Display styles
**Display Styles Directory** makes all colour schemes contained in the selected folder available in the model as default display styles, without needing to select the colour files again.
#### Link mapping
**Link mapping file** creates links to external documents in the object attributes, as defined in the mapping file. Refer to the **Linking** chapter in the UPV documentation for information on how to create a link mapping file.
#### PID 3D mapping
The **PID <-> 3D mapping** file creates links between PID objects and their 3D counterparts. Refer to the AdapterForSpid documentation for information on how to create a PID 3D mapping file. A database must be selected in [IntelliPID database](#intellipid-database) for the mapping file to work. To create a PID 3D mapping file, an Excel sheet must contain the following cells:
`IntelliPidAttribute` and `3DAttribute` must contain the names of the attributes to be mapped. `IntelliPidRegEx` and `3DRegEx` must contain the regular expression commands required to make the values of the IntelliPid and 3D attributes match. Only character deletion is allowed; no characters may be added with the regular expression command.
> Any `.xlsx` file can be selected when browsing for link or PID mapping files, but only files structured as described in the relevant documentation will work as intended.
#### Reuse 2D/3D projections
The **2D <-> 3D mapping** source directory defines the location of `.upvf` file or files containing picture-based 2D/3D projections that should be made available again in the new UPV model. Images from 2D/3D projections stored in those `.upvf` files are converted directly into the UPV model.
When selected, user authentication is required for downloaded models.
When **Allow download** is selected, a user can download the model to a local machine instead of working only with a server-based version.
When selected, the view cube in UPV shows XYZ coordinates instead of compass directions. This is only the default view mode and can be changed later in the UPV settings.
## Tools settings
The **Tools Settings** provide many advanced configuration options for the generated output.
### General
#### Export caching
The **Export Caching** option enables the program to reuse already calculated laser scan data. If the same laser scan model is exported repeatedly, the program saves time by reusing already calculated information. Only changes generally need to be recalculated.
> This option works best with laser scan data, but 3D data is also supported.
> This option results in significantly larger data files in exchange for faster processing.
#### Configuration file
Select the initial configuration file for the UDiTH model. This can later be changed in UPV itself.
> Any `.ini` file can be selected when browsing for a configuration file, but only files structured as described in the **Configuration File** chapter of the UDiTH documentation will work as intended.
#### Aspects
Select or deselect if a specified aspect should be part of the 3D model.
### Tree
The tree hierarchy shown in UPV can be edited. Select attributes by clicking the checkbox next to them and then use the right arrow button to add them to the list, or the left arrow button to remove them. Objects with those attributes show them in the order in which they were added to the tree bar.
### Attributes
Drag and drop attributes to or from **Used attributes** if they are to be shown in UPV when an object with the specified attribute is selected.
Multiple attributes can be moved by selecting the checkbox next to them and using the arrows between the lists.
### Mapping
Mapping allows the transformation, rotation, and scaling of multiple models.
1. These options are used for rotation and scaling. This step is always processed first.
In this example, `Model1.upvc` rotates around `-100,50,0` metres. Always use metres as the unit.
2. In the second step, the model is moved by the specified distances to its destination.
---
---
### Advanced Transformation of UPVC Files
The Builder provides an additional option to apply **translation, rotation, and scaling** to UPVC files during model creation.
### General Concept
In addition to the UPVC file, an **INI file** can be placed in the same directory.
The INI file must have **exactly the same filename** as the UPVC file.
If present, the Builder will automatically read transformation parameters from this INI file and apply them when generating the UPV/UDiTH model.
---
### INI File Parameters
The INI file defines the transformation using the following parameters:
- **Point of Rotation**
Defined in SI units \([m]\)
- **Rotation Angle**
Defined in degrees \([deg]\)
- Positive values = counterclockwise rotation
- Rotation can be applied around all axes
- **Translation**
Defined in X, Y, and Z directions
Example of INI files next to UPVC files:
Example of INI file:
```ini
[rotation]
# Point of Rotation in SI-unit [m]
# Rotation Angle in [deg] - positive value = CounterClockWise
# Only rotation around one axis is possible
pointX=45
pointY=6
pointZ=0
AngleX=0
AngleY=22.5
AngleZ=-45
[translation]
X=30.125
Y=-15.369
Z=0
[scale]
scale=1.5
```
---
### Logging
All applied transformations are fully documented in the **Builder log file**.
This includes the complete transformation applied to the UPVC during processing.
---
### Interaction with UPVM Files
The existing **UPVM-based transformation concept** remains supported.
However, the following rules apply:
- If an INI file exists alongside the UPVC file (same name),
**the INI transformation values take precedence**
- In this case, **UPVM transformation data is ignored**
- This behavior also applies to **batch processing**
---
### Summary
- Optional INI file enables direct transformation control per UPVC file
- Supports rotation (all axes), translation, and scaling
- INI overrides UPVM if both are present
- Fully traceable via Builder log output
---
---
>
**Use as catalog** is not applicable yet.
---
---
### Advanced options
#### Document databases
Document databases are `.upvd` files. Add or remove the required files as needed. Refer to the AdapterForDocuments documentation for information on how to create document database files.
**Include all drawings:** All drawings are included in the model, regardless of whether they contain a reference to an object in the model.
#### IntelliPID database
IntelliPID databases are `.upvp` files. Add a single file. To connect PID and 3D objects, also add a PID 3D mapping file as described in [PID 3D mapping](#pid-3d-mapping).
### Plugins
Plugins are C# libraries created with the CAXperts plugin API. To move plugins into or out of **Used plugins**, select the checkbox next to the plugin and use the arrow buttons between the lists.
The plugins themselves, together with their config files if required, must be stored in the local `%AppData%` folder of the machine running UPVBuilder.
### Command-Line Parameter Guide
1. **Prepare your files** - Ensure that you have the required input files ready.
| Parameter | Example | |
|---|---|---|
| ```-input:``` | ```C:\Input\Example.upvc``` | Path to the file or directory that you want to convert into a UPV file. |
| ```-expirationdate:``` | ```"2099-31-12T23:59:59.9999999" OR "+30"``` | Sets an expiration date for the exported file. You can specify either a fixed date or a duration in days. |
| Parameter | Example | |
|---|---|---|
| ```-output:``` | ```C:\Output\Example\Output``` | Path where the model files are saved. |
| ```-color:``` | ```C:\Settings\Color.xls``` | Path to a file that contains colour configurations. |
| ```-config:``` | ```C:\Settings\Example.ini``` | Path to the configuration file used for processing. |
| ```-intellipidmapping:``` | ```C:\Settings\IntelliPidMapping.xlsx``` | Path to a file used for IntelliPID mapping. |
| ```-package:``` | ```C:\Input\PackagesDefinitionFile.xlsx``` | Path to a file defining package definitions. |
| ```-disablesearchindex:``` | Disables creation of a search index file. | |
| ```-outputplugins:``` | Outputs registered plugin names in the result. | |
| ```-disablepdfcache:``` | Disables creation of PDF cache entries. | |
| ```-pdfcachemaxdp:``` | ```512``` | Determines the highest DPI used for PDF caching. Allowed values are `128`, `512`, and `1024`. |
| ```-includealldrawings:``` | Specifies whether all drawings or only linked drawings should be included. | |
| ```-plugin:``` | ```ExamplePluginName``` | Enables a specific plugin. |
| ```-drawing:``` | ```C:\Input\Example.upvd``` | Path to a drawing file. |
| ```-intellipiddatabase:``` | ```C:\Settings\IntelliPidDatabase.upvp``` | Path of an IntelliPID database file. |
**Output file:** Defines the path to the `*.upvc` output file. This file contains all required information, such as graphics and attributes, needed to generate UDiTH or 3D PDF output using CAXperts **UDiTH Builder**.
If the `*.upvc` output file already exists, **AdapterForSmartReview** works in update mode and captures only the changes.
### Settings
All settings are stored automatically in the configuration file in the user profile. The location of this configuration file can be changed via **Tools** → **Settings**.
### General
**Configuration file:**
To export the settings, use **File** → **Save settings to file**:
To import settings from a file, use **File** → **Load settings from file**.
> **Load settings from file** does not change the current location of the configuration file. Once the settings have been imported, any further changes are stored in the current configuration file shown in the **Tools** → **Settings** menu.
**Aspects:**
All aspects from the SmartPlant Review session are captured automatically. No additional settings are required.
### Advanced
**Consider existing Display Sets** - If enabled, the visibility, for example whether objects are switched on or off in the Main View, and the colours are taken from the existing Smart Review Display Sets for `*.vue` files. This does not apply to `*.svf` session files.
**Maximum objects per capture group** - This is the maximum number of objects captured at one time. Higher values improve performance, but may also cause the Smart Review MDB file to overflow, as it is limited to a maximum size of `2 GB`. A value of `35000` is suitable for most sessions.
**Stroking tolerance** - Defines the quality of the exported graphics. Higher values mean better graphical quality, but they also increase the size of the exported graphics.
**Advanced Graphic Handling** - If this option is enabled, advanced measurement options become available in Universal Plant Viewer, for example snapping to edges.
**Use PDS Levels as Aspects** - Applicable only to DRI sessions. If enabled, every MicroStation level is treated as a separate aspect.
**Force attribute extraction** - Applicable when processing against an existing `*.upvc` file in update mode. If enabled, all attributes are extracted again, even when the individual objects in the existing `*.upvc` file are already up to date.
**Process modified vue-files completely** - This option mainly applies to `*.svf` sessions, where you want to reprocess complete `*.vue` files instead of individual objects within those files.
## Command Line Mode
> Due to restrictions in Smart Review, absolute paths must be used in AdapterForSmartReview command-line commands.
**AdapterForSmartReview** can also be used in command-line mode. Use the following command to display the available command-line arguments:
**C:\\\>"C:\\Program Files\\CAXperts\\AdapterForSmartReview\\AdapterForSmartReview.exe" /?**
The command-line arguments are shown after entering `/?`:
**AdapterForSmartReview** requires access to the desktop in order to run **Smart Review**. Therefore, to run the software as a scheduled task, the following steps are required:
1. Download **
If this window does not appear, make sure that the **Interactive Services** service is enabled in the Windows Control Panel.
To return from the session `0` console to the main desktop, press the following button:
>
- `D:\AdapterForSmartReview_Batch.bat` runs in a separate session. The active user can continue working in Windows or log off. Session `0` continues running in the background.
- The `D:\AdapterForSmartReview_Batch.bat` script is executed under the `LocalSystem` account with limited permissions and without network access. Input and output files must therefore be located on a local drive. If you need network access, for example to copy the resulting `*.upvc` file to a network drive, add the corresponding commands to the end of `D:\AdapterForSmartReview_Batch.bat`.
## Advanced Features
### Advanced configuration for capturing graphics
This chapter is intended for advanced users. You can ignore it if advanced configuration is not required.
There are two types of `.ini` file: `User.ini` and one `.ini` file per project.
`User.ini` contains general settings that are valid for all projects. `Project.ini` contains only project-specific settings.
### Ignore objects (Project.ini)
The file size of the resulting PDF file depends noticeably on the number of objects captured. Ignoring less-meaningful objects (e.g. welds in **SmartPlant 3D** sessions) is one approach for reducing the overall 3D PDF file size.
The following syntax is used to define a custom object type in the `.ini` file:
```ini
[ObjectDefinition]
ObjectTypeName=AttributeName Operator Value
```
Example:
```ini
[ObjectDefinition]
MyWeld=Component=Weld
```
`[ObjectDefinition]` is the section name in the `.ini` file. `MyWeld` is the object type name and can be defined freely. `Component` is an attribute name that must exist in the design review session. The `=` character after `Component` is the operator. The operator can be `=` or `<>` for equality, or `like` and `not like` when using wildcards. `Weld` is the attribute value.
The example defines an object type `MyWeld` for objects whose attribute `Component` is equal to the value `Weld`. You can then create rules to ignore objects of type `MyWeld` using the following syntax in the `.ini` file:
```ini
[ObjectsToIgnore]
MyWeld=1
```
The `.ini` file is named `AdapterForSmartReview.ini` and is copied automatically from the installation template into the folder of the design review session loaded in **AdapterForSmartReview**. By default, the following definitions are included in the `.ini` file to ignore welds in **Smart 3D** sessions:
```ini
[ObjectDefinitions]
Weld= Component=Weld
Weld1= Commodity type Like *weld*
Weld2= Weld Type Like *weld*
Weld3= Type Like *weld*
[ObjectsToIgnore]
Weld=1
Weld1=1
Weld2=1
Weld3=1
```
## UseHierarchy (`User.ini`)
`UseHierarchy` is a user setting that reads the content of hierarchical labels in SPR.
`UseHierarchy=1` means that all hierarchical SPR labels are read from a `*.vue` file.
## SkipMissingModels
This setting applies only to the processing of `*.svf` sessions in batch mode. `*.svf` sessions can contain a large number of `*.vue` files. Missing individual `*.vue` files would normally stop the AdapterForSmartReview process. An internal default setting automatically skips missing `*.vue` files when the process is executed in batch mode or by using the UPC (UniversalPlantCreator).
## Log files
The software creates log files in the local `TEMP` directory, for example `C:\Temp\AdapterForSmartReview\`. You can also open these files by double-clicking the CAXperts **AdapterForSmartReview** status bar:
---
# UDiTH Capture Station — AdapterForNavisworks
# AdapterForNavisworks
**AdapterForNavisworks** captures 3D graphics and attributes from Autodesk Navisworks sessions and stores them in a `UPVC` file. This file is then used as input for the **Builder** to generate UPV models.
## Working with **AdapterForNavisworks**
## Prerequisites
**AdapterForNavisworks** works with Navisworks Simulate or Manage, versions 2020 to 2027.
After installing **AdapterForNavisworks**, check in Navisworks that the **CAXperts Adapter for Autodesk Navisworks Plugin** is available under **Tool add-ins**.
## Interactive Mode
Start **AdapterForNavisworks** and select either one **input file** or multiple **input files**. All file types supported by Navisworks are also supported by the adapter.
**Output file:** Defines the path to the `UPVC` output file. This file contains all required information, such as graphics and attributes, needed to generate UDiTH or 3D PDF output using CAXperts **UDiTH Builder**.
If the `UPVC` output file already exists, **AdapterForNavisworks** works in update mode and recaptures only those files whose last modified date has changed.
| **AdapterForNavisworks** includes a built-in mode for parallel processing of input files. |
| For faster processing, it is better to use multiple smaller files rather than one large file containing the same model. |
---
# UDiTH Capture Station — AdapterForE3d
# AdapterForE3d
**AdapterForE3d** captures 3D graphics and attributes from AVEVA PDMS sessions, for example `*.rvm` and `*.att` files, and stores them in a `*.upvc` file. This file is then used as input for CAXperts **UDiTH Builder** to generate Universal Plant Viewer or 3D PDF sessions.
## Using AdapterForE3d
Start **AdapterForE3d** and select either one **input file** or multiple **input files**. PDMS `*.rvm` files are supported. Attribute files, such as `*.att` or `*.txt`, should be located in the same folder and should have the same name as the related `*.rvm` files.
**Output directory:** Defines the path to the `*.upvc` output file. This file contains all required information, such as graphics and attributes, needed to generate UDiTH or 3D PDF output using CAXperts **UDiTH Builder**.
If the `*.upvc` output file already exists, **AdapterForE3d** works in update mode and recaptures data only if the last modified date of the `*.rvm` file is newer than that of the `*.upvc` file.
## Aspects for PDMS models
In PDMS, it is possible to export 3D graphics together with additional aspects, for example insulation and obstruction. Because these aspects cannot be exported separately, but only together with the base graphic (`Simple Physical`), several files are produced that contain the base graphic plus the additional aspect.
AdapterForE3d can use an additional text file to assign this extra graphic directly to a corresponding aspect in the UPV model.
A template for this file is available at `C:\Program Files\CAXperts\AdapterForE3d\Templates\Aspect.txt`.
This file only needs to be present and adapted during conversion with the PDMS adapter in the directory where the `*.rvm` files are located.
You only need to specify the syntax of the files containing this additional aspect graphic.
This creates the additional graphics from the `*.rvm` files on separate aspect layers in UPV, where they can easily be switched on and off in the model.
`PDMS-Model.rvm` contains only the base graphic and is assigned to `Simple Physical`.
`PDMS-Model_Insulation.rvm` contains the base graphic and the insulation graphic and is assigned to `Insulation`.
`PDMS-Model_OBSTR.rvm` contains the base graphic and the obstruction graphic and is assigned to `Obstruction`.
## Additional `.ini` Parameters
Additional parameters can be defined in the `.ini` file.
The `.ini` file is usually located in `%AppData%\CAXperts\AdapterForE3d`.
### `unset` Attributes from E3D/PDMS
By default, all attribute values set to `unset` are skipped by AdapterForE3d.
However, these attributes can still be imported by adding an entry to the `.ini` file.
Import all attributes with the value `unset`:
```ini
[UnsetAttributes]
Unset=1
```
Import selected attributes with the value `unset`. Attribute names are separated by semicolons:
```ini
[UnsetAttributes]
Unset=mto; EQP_Status; Approval_date
```
### Remove Duplicated Aspect Graphics
When exporting `*.rvm` files from PDMS, the aspects `Insulation` and `Obstruction` are always exported together with the basic solid graphic.
As a result, graphic elements may appear several times in the model. This can reduce viewing performance, especially in very large models. These duplicate graphics can be removed from the model afterwards by using an additional switch setting as a post-process step. This post-process may increase the conversion time.
```ini
[Settings]
RemoveDuplicatedAspectGraphics=1
```
### Do Not Group Equipment Graphics
By default, the individual primitives of a piece of equipment are grouped together. This results in a smaller model size with fewer objects in UPV, which has a positive effect on navigation speed. However, this grouping can be disabled so that the smallest object units remain the primitives themselves.
```ini
[Settings]
DoNotGroupEquipment=1
```
## Command line mode
**AdapterForE3d** can also be used in command line mode. Use the
following command to show the command line arguments:
```
C:\\\>"C:\\Program Files\CAXperts\\AdapterForE3d\\AdapterForE3d.exe" /?
```
Command line arguments:
`-input:C:\Example.rvm`
Occurrence: `AtLeastOnce`
Help text: Path to a PDMS `*.rvm` file or a directory containing multiple PDMS `*.rvm` files.
`-output:C:\Output\Example.upvc`
Occurrence: `AtMostOnce`
Help text: Path of the output file.
`-log`
Occurrence: `Arbitrary`
Help text: Path of the log file. If not defined, the log file is placed in `C:\Users\
---
# UDiTH Capture Station — AdapterForIfc
# AdapterForIfc
**AdapterForIfc** extracts graphics and attributes from *Industry Foundation Classes (IFC)* files and saves them in a `.upvc` file. This file is then used as input for the **Builder** to create UPV models.
Note: As of version 2026.3.4, the AdapterForIfc correctly decodes the IFC GlobalId to the internal UID.
If you would like to keep the previous behavior, please add the following entry to the INI file located in %appdata%\CAXperts\IFC Adapter\
**Output File** specifies the path for the **.upvc** file, which contains all necessary information, such as graphics and attributes, required to generate UPV models with **UDiTH Builder**.
## Command Line Mode
**AdapterForIfc** can also be started in command line mode.
To get all parameters directly in a command window, just type:
`C:\Program Files\CAXperts\IFC Adapter>"IFC Adapter.exe" -?`
Available parameters are:
-output:C:\\Output\\Example.upvc (Occurence: ExactlyOnce; Help Text: Path
to where the UPVC file will be created. File extension 'upvc' will be added, if not present.)
-input:C:\\Input\\Example.ifc (Occurence: AtLeastOnce; Help Text: Path to a IFC Adapter session file.)
-aspect:Simple physical (Occurence: Arbitrary; Help Text: The aspect to use.)
-config:c:\\config.ini (Occurence: Arbitrary; Help Text: The config file to use.)
-licensekey (Occurence: Arbitrary; Help Text: Activate license key.)
-log (Occurence: Arbitrary; Help Text: Log file path. If not defined, log file is placed in C:\\Users\\CAXperts\\AppData\Local\Temp)
## Log Files
The software generates log files in the local TEMP directory (e.g., "C:\\Temp\\IFC Adapter\\"). Users can access these files by double-clicking on the status bar of CAXperts **AdapterForIfc**:
---
# UDiTH Capture Station — AdapterForLaserScans
# AdapterForLaserScans
**AdapterForLaserScans** captures point data from **E57** files and saves it as a **.upvc** file.
This file is then used as input for CAXperts **UDiTH** to generate visualisations.
## Supported Formats
### Laser scan
- E57
> Results may be better if the scanning position is included.
### Panorama
- TruViews
- LFM Panoramas
### Mesh
- OBJ (may include optional MTL and texture files)
## Overview
This section provides a brief overview of the main functions of **AdapterForLaserScans**.
For more detailed information, please refer to the dedicated chapters or [visit our help center](https://help.caxperts.com/).
### Operating Principle
**AdapterForLaserScans** converts point cloud data from a *laser scan file* into a *tessellated mesh*.
It removes duplicate points and optimises cloud density.
AdapterForLaserScans also integrates 3D textures into the laser scans, as illustrated below:
### Interface
Select the input folder for AdapterForLaserScans and the required target folder.
## Settings
### Meshing Options
### \%temp% Option
Given the large file sizes of laser scan data, you can specify the data path for temporary storage. Click **Browse** to select your preferred folder location.
>
The size of the laser scan files may affect the loading time of AdapterForLaserScans. Overlapping sections of each scan are compared.
### Configurations
**Create `defaultConfig.upv` with views** - This option creates default settings to save laser scan data (`.upv` files) with predefined views.
**Delete temporary files** - Enabling this option ensures that temporary files are deleted regularly to free up space.
| Image/Texture/Panorama Settings | |
|---|---|
| Convert generated images to panoramas | When this option is enabled, you can choose a viewing point directly from the laser scan. If it is disabled, panoramas are not available through the red `360°` markers. |
| Fill images | Enabling this option improves the quality of the generated images. *This does not work for TruViews and panoramas.* |
| Resolution | Adjusts the quality of the `360°` image. Move the slider to the left for lower quality (`4000 × 2000` pixels) and to the right for higher quality (`16000 × 8000` pixels). |
Using the highest resolution can reduce performance.
| OBJ Import | |
|---|---|
| Aspect to use | .obj files can be imported. In **Settings** under **Aspects**, .obj files can be deactivated separately. |
Available parameters are:
- `-input:C:\Input` (`Occurrence: ExactlyOnce`; Help Text: Path to a folder containing TruViews and laser scans)
- `-output:C:\Output\Example.upvc` (`Occurrence: ExactlyOnce`; Help Text: Path to where the UPVC file is created. File extension `upvc` is added if it is not already present.)
- `-licensekey` (`Occurrence: Arbitrary`; Help Text: Activates the licence key.)
- `-log` (`Occurrence: Arbitrary`; Help Text: Path to the log file. If not defined, the log file is placed in `C:\Users\CAXperts\AppData\Local\Temp`.)
## LaserscanAdapter
To locate this configuration file for editing, you can use the following path:
`%AppData%\CAXperts\LaserscanAdapter\ Replace `| Parameter | Default Value | Description |
|---|---|---|
| BoxSize | 4 [meters] | The mesh is split into boxes of `4 × 4 × 4` metres. If a box is too large or contains too many points, it can be split into smaller boxes. This speeds up calculations. Use the default size for indoor scans. For outdoor scans, such as landscapes or drone scans, use sizes greater than `10` metres. |
| FurthestScanDistance | 30 [meters] | Points farther than this distance from the scanner are ignored and removed. For example, with the default setting, a point `30.1` metres away is deleted. |
| PointSamplingRate | 1 | This defines how often points are sampled from the point cloud. For example, if it is set to `3`, every third point is used for mesh calculations. |
| ForceRgbMesh | 0 | When set to `1`, the system uses RGB information from the point cloud. This replaces the use of panorama textures. |
| SimplifyMeshes | 1 | When set to `1`, the system reduces the number of triangles in the mesh after triangulation while maintaining good mesh quality. |
| Simplification | Between 0.001 and 0.000001 depending on the quality | The higher this value, the more strongly the mesh is simplified. This results in fewer triangles. |
| OctDownMaxNodeSize | 0.02 [meters] | This determines the level of downsampling and affects the density of the point cloud used for meshing. A lower value means more points and more triangles. The recommended range is between `0.05` and `0.5` metres. |
| RemoveGhostObject | 0 | When set to `1`, this removes parts of the point cloud that move and are not consistent across different scans. |
| FumeCheck | 0 | When set to `1`, this removes fumes in the air. It works only if the `RemoveGhostObject` parameter is also set to `1`. |
This button enables processing of the isometric drawing into a `UPVD` file.
**AdapterForDocuments** starts **SmartSketch** and extracts the drawings into a `UPVD` file.
When you combine the `UPVD` file with the 3D model in **UDiTH Builder**, the resulting UPV session contains 3D objects linked to 2D isometric drawings, and vice versa:
|
|
An example for a mapping file is available in "C:\\Program Files
(x86)\\CAXperts\\AdapterForDocuments\\Templates\\PDF-Mapping.xlsx"
The synchronise button writes all links into the selected mapping-file.
## Conversion of PDMS/E3D isometric drawings
**AdapterForDocuments** can also convert PDMS/E3D isometrics. The converted isometrics include intelligent hotspots for all parts except straight pipes, so they have a direct link to the 3D model, just like S3D isometrics.
For this to work, the isometrics must be exported from PDMS as PDFs together with their hit files. This is an option within PDMS iso creation.
## Additional settings
By default, AdapterForDocuments allows a single drawing name.
## Command line mode
**AdapterForDocuments** can also be started in command line mode. To get all
parameters directly in a command window, just type:
\"C:\\Program Files
(x86)\\CAXperts\\AdapterForDocuments\\AdapterForDocuments.exe\" /?
Available parameters are:
-output:D:\\path\\to\\file.upvd (Occurance: ExactlyOnce, Help Text: Path
to the output file)\
-sp3dfolder:C:\\drawings (Occurance: AtMostOnce, Help Text: Path to the
sp3d input folder)\
-pdffolder:C:\\pdfs (Occurance: AtMostOnce, Help Text: Path to the pdf input folder)\
-pdmse3dfolder:C:\pdmsE3d (Occurance: AtMostOnce, Help Text: Path to the pdmsE3d input folder)
-pdfmappingfile:C:\\pdfConfiguration\\mapping.xlsx (Occurance: AtMostOnce, Help Text: Path to the pdf mapping input file)\
-hierarchicalupdate (Occurance: AtMostOnce, Help Text: Determines
whether the dircetory structure of moved drawings should be updated)\
-onlycheckednodes (Occurance: AtMostOnce, Help Text: If selected, only
the checked nodes/drawings/pdfs will be updated/added. Otherwise all
nodes in all sub folder of the given folder will be considered).
Possible syntax for command-line:
\"C:\\Program Files
(x86)\\CAXperts\\AdapterForDocuments\\AdapterForDocuments.exe\"
-output:D:\\path\\file.upvd -sp3dfolder:C:\\drawings -pdffolder:C:\\pdfs -pdfmappingfile:C:\\pdfConfiguration\\mapping.xlsx
## Log files
The software creates log files in the local TEMP directory (e.g.
"C:\\Temp\\AdapterForDocuments\\". The user can also open these files by
double-clicking on the CAXperts **AdapterForDocuments** status bar:
---
# UDiTH Capture Station — AdapterForSpid
# AdapterForSpid
## Introduction
The purpose of **AdapterForSpid** is to extract data used by Intergraph Smart® P&ID (SPID) into a local `UPVP` database for use with UDiTH.
## Graphical User Interface (GUI)
### Invoking **AdapterForSpid**
After starting, the following UI will appear:
### Loading a plant
The software automatically connects to the active plant. It is displayed in the field **Plant** and can be changed using the **Change active plant\...** button.
From the **Open plant structure** dialogue, you can select another plant from the active site. Plants from other sites can be accessed by using the **Site server\...** button.
Before loading the plant data, the **Output Access file** must be specified using the **Browse\...** button.
## Extracting data
Clicking the **Extract** button starts extraction from the selected plant. The following extraction options are available: **All**, **Selected drawings**, **Associated data**, and **Extract drawing files**.
### General extraction settings
#### All
The **All** option extracts all plant data without requiring further configuration.
#### Selected drawings
The **Selected drawings** option starts the extraction with a dialogue in which the required drawings can be selected.
A list of available drawings from the active project appears.
Select the required drawings in the dialogue and press **OK** to start the extraction.
In Connected Workshare projects, drawings that belong to the satellite are displayed in red so that the user is informed about their status.
#### Associated data
The **Associated data** option starts the extraction with a dialogue in which the required data can be defined by using SQL statements.
For example, the statement shown above extracts only pipe runs whose tags begin with `05`.
In the same way, it is possible to extract only pipe runs with `FluidSystem` set to `Water` or `Nominal Diameter` set to `100 mm`.
The same interface can also be used to search data, for example to check whether a certain sequence number has been used in the plant. The yellow bar can be used to enter a search string without performing the extraction:
#### Revision
The **Revision** option allows extraction of frozen data, but only for revisions that have an associated version. The dialogue allows you to select either the **Last Revision** data or the data for a specific revision:
### Settings related to the from/to calculation
The following options can be used when extracting the from/to information:
**Only equipment tag:** Reports only equipment tags, not nozzle tags.
**No branches:** Does not report branch connections.
**Use component description if no tag:** Reports the `Piping Component Description` attribute if the component tag is empty and if the component is an `EndComponent`.
In addition to these settings the following changes were implemented:
#### Tema heat exchangers
If the front and rear sections do not have their own item tags defined, the shell item tag is also extracted as from/to information for pipe runs connected to the front or rear section.
In the example above, all runs connected to the parts of the heat exchanger have `W-170` as from or to information.
#### Equipment with no tag
For equipment without a tag, it is possible to use a variable that tells the software which attribute to use as from/to information, for example `Name` or `Description`.
This is done by using the PID ReportAdapter `.ini` file:
`...\Program Files (x86)\CAXperts\IntelliPID Adapter\IntelliPID Adapter.ini`
```ini
[FROM_TO]
Equipment_NoTag=Name
```
## Additional SQL statements
### Create additional SQL statements
SQL statements can be used to extend standard output tables with user-defined attributes or to perform other tasks, such as creating additional tables or queries. These statements can be defined using **Tools → Additional SQL statements**. They are executed automatically after the extraction process has been completed.
The additional SQL statements can be entered in the **Additional SQL statements to be processed after extraction** field. They should follow the format shown in the following examples:
`SQL1=ALTER TABLE Equipment ADD COLUMN [MyAttribute] VARCHAR(255)`
`SQL2=UPDATE [Equipment] SET [MyAttribute] = 'Test'`
The tables that can be used in the queries are those created during extraction. Additional tables, if required, must be copied before extraction into the `template.mdb` database, which can be found in the application folder.
### Use query builder
The included query builder can help you create SQL statements.
Create a new statement with the **Add** button and add one of the **Available SQL query templates** to it. Clicking **Add query**, or double-clicking a list item, inserts the query at the cursor position or replaces the selected text.
The **Available SQL query templates** look like this:
`UPDATE [%TABLE1%] SET [%TABLE1%].[%COLUMN1%]=`
When the template is used, the `%TABLE1%` and `%COLUMN1%` placeholders are filled with the table name and column name selected in the corresponding fields.
The `%TABLE1%` and `%COLUMN1%` fields are filled from the Access database defined for extraction output, which also includes the tables from `Template.mdb`. This means that the fields are filled only after extraction has been performed at least once.
If the **Show hidden tables** option is selected, all tables in the database can be chosen when building the query. If it is not selected, only the tables displayed in **UniversalReporter** are available, and tables created for internal use are hidden.
### Create new SQL query template
User-defined **SQL query templates** can be created. To add a new template, click the **Add** button and enter the template name.
Enter the SQL statement text and the placeholders for the **Tables and columns to be used by query** text boxes by using the `%TABLE1%` and `%COLUMN1%` buttons.
User-defined templates can be deleted or modified by using the **Remove** or **Edit** buttons.
> The SQL text boxes support syntax highlighting.
### Additional Settings
To ensure correct extraction for projects with a large number of P&IDs, it is recommended to set the parameter `BigPlant=1`.
For projects that include P&IDs with auxiliary graphics, you can use the parameter `auxiliary=1` to divide the full auxiliary graphics into individual graphical elements.
These parameters can be added to the `IntelliPID Adapter.ini` file located in the adapter installation folder.
## Configure attributes
### General functions
Select **Tools -\> Attribute configuration\...** to open the **Attribute
configuration** dialog.
Select **Tools -> Attribute configuration...** to open the **Attribute configuration** dialogue.
The following window appears.
In this dialogue, you can define the attributes to be extracted.
At present, attributes can be added for the following object types: `InlineComp_Prun`, `Eqp_Nozzle`, `PlantItems`, `Instruments`, `ItemNotes`, `OPCs`, and `Drawings`.
Additional attributes, which are not available in SmartPlant P&ID and are created during extraction, are displayed in blue, for example `End_2_ConnectedPiperunID` in the screenshot above.
The numbers displayed on the right side of the tables correspond to the number of available attributes on the left and the number of selected attributes on the right.
Expand the tables and select the required attributes. These can then be transferred to, or removed from, the **Attributes to be used** pane by using the `>` and `<` buttons.
### Filter
You can also search for specific attributes by using wildcard filters. In the following example, the search is for an attribute name containing `Flui` in the `InlineComp_Prun` table.
>
### Saving attribute configuration
The attribute configuration is saved in the folder `%APPDATA%\CAXperts\IntelliPID Adapter\` with the file name `PlantName.ini`. The attribute configuration can also be saved for backup or for batch-mode extraction by using:
## Attribute configuration specialties:
### ParentPlantGroup and UnitCode
For SPEM hierarchies such as `Plant\Area\Unit`, it is possible to extract both the `ParentPlantGroup` information and the `UnitCode` information:
This allows easy filtering, for example by area. The selection is available for all objects except `ItemNotes` and `OPCs`.
### PipingPoint attributes including ConnectedPiperunID
For piping connection points `1` to `4`, it is possible to extract attributes such as nominal diameter and description, as well as the `SP_ID` of the connected pipe run. This information can be used to create a report showing the pipe run connected to the second side of a pressure-reducing valve.
The result in **UniversalReporter** looks like this:
### CaseProcess SI values (also other properties SI values)
The SI values can also be selected for extraction.
### Filename and quantity
If `Filename` is selected at the `PlantItem` object level, the symbol name is also extracted, making it possible to see how often a symbol is placed on a drawing.
If `Quantity` is selected, which is available on all object levels, each extracted object is assigned the quantity `1`. In **UniversalReporter**, it is then possible to create `Sum_of_quantity` in order to identify the total number of valves, for example.
### Connectivity attributes for the relations "Equipment to PipeRun" and "Instruments to PipeRuns or Equipments"
Although they are not visible in the attribute configuration interface, the following two attributes are extracted:
- **Nozzle_ConnectedPipeRunID** for the `Eqp_Nozzle` table
- **Instrument_ConnectedItemID** for the `Instruments` table
These attributes can be used to create reports in which the pipe runs connected to an item of equipment are listed, starting at the equipment object level, or to identify instrument connections, which may be to pipe runs or equipment nozzles.
**Example for the Equipment_PipeRun Relation**:
**Example for the Instrument Connection Report**:
There are multiple ways to connect instruments to nozzles or pipe runs.
The following connections, related to piping components placed between the connected pipe run or connected equipment nozzle and the instrument, have been modified in PID ReportAdapter:
**A**: The instrument is connected to a valve placed in a branch of the main pipe run. The branch is returned as the connected object.
**B**: The instrument is connected to a valve that is connected to a nozzle, where the pipe run type is `Conn to process/Supply`. In this case, the nozzle is returned as the connected object.
**C**: The instrument is connected to a valve that is connected to a nozzle through a `ZeroLength` pipe run. In this case, the nozzle is returned as the connected object.
**D**: The instrument is connected to a valve placed in a pipe run that is itself connected to a nozzle. The pipe run has a special line type. In this case, the nozzle is returned as the connected object. In the example below, the line type is `Components only`.
The definition of the pipe run type can be set in `..\PID ReportAdapter.ini` with the following entry:
```ini
[Instr_Conn]
Nozzle_Pruntype = "Components only"
```
Details for C and D:
Result:
### Disconnected piperuns having the same ItemTag
If `NotConnectedRuns` is selected at the `InlineComp_Prun` object level under `Others`, the number of disconnected pipe runs with the same tag is calculated for the extracted dataset.
Within a drawing, the function checks whether the runs are graphically connected. Across drawings, it checks whether the pipe runs are connected via `OPCs`. Any result greater than `0` indicates duplicate pipe run tags that are not graphically connected.
Warning whenever the database is opened.
The extraction of `NotConnectedRuns` can take some time for larger datasets.
### Identify number of LineNumberLabels placed on a piperun
For all pipe runs, except instrument runs and zero-length pipe runs, if the attribute `NumberofLabels` is selected and the label name or names are defined in the plant-specific `.ini` file, the number of labels placed on each pipe run is calculated during extraction.
In the `.ini` file, located at `.UserProfile\AppData\Roaming\CAXperts\AdapterForSpid\`
`
**Examples:**
`"C:\Program Files (x86)\CAXperts\IntelliPID Adapter\IntelliPID Adapter.exe" -upvp:"d:\temp\PlantA.upvp"`
`"C:\Program Files (x86)\CAXperts\IntelliPID Adapter\IntelliPID Adapter.exe" -upvp:"d:\temp\PlantA.upvp" -site:"d:\Site1\smartplantv4.ini" --plant:PlantA --parentplant:PlantA --config:"d:\PlantA.ini"`
`"C:\Program Files (x86)\CAXperts\IntelliPID Adapter\IntelliPID Adapter.exe" -upvp:d:\temp\1.upvp -pbs:Refining Area\Recovery Unit;\Refining Area\Distillation Unit\a_*`
> This saves all drawings with names starting with `a_` and located in `Refining Area\Recovery Unit` or `Refining Area\Distillation Unit`.
`"C:\Program Files (x86)\CAXperts\IntelliPID Adapter\IntelliPID Adapter.exe" -upvp:d:\temp\1.upvp -unitcode:03`
> This saves all drawings located below the unit with the unit code `03`.
The parameters `-pbs` and `-unitcode` must be used separately, that is, either `-pbs` or `-unitcode`.
The attribute configuration `.ini` file, used in the command line with the `-config` parameter, can be created by using the menu **File - Save settings to file**.
The options **Extract Drawing Files** and **Extract From-To relations for InlineComp_Prun** from interactive mode are saved in the file
`%APPDATA%\CAXperts\IntelliPID Adapter\config.ini`
for example `C:\Documents and Settings\UserName\Application Data\CAXperts\IntelliPID Adapter\config.ini`.
In command-line mode, these two options are read from `config.ini` and used for extraction.
---
# UDiTH Capture Station — AdapterForPdfPid
# AdapterForPdfPid
## Introduction
The purpose of **AdapterForPdfPid** is to extract data from different PDF files into a local `UPVP` database.
**AdapterForPdfPid** scans PDFs and creates a semi-intelligent P&ID database file for later use in Builder and IntelliPID.
The program recognises **text labels** and sorts them into user-defined categories such as equipment, pipe runs, instruments, and off-page connectors.
The user-defined categories for label recognition must be stored in an Excel worksheet.
The name of this file must be **config.xlsx**.
An example of `config.xlsx` can be found in:
> `\Program Files\CAXperts\PdfPidAdapter\Templates`
The names of sheet 1 and sheet 2 can be changed. It is important only that both sheets remain in the correct order.
Sheet 1 = `Patterns`
Sheet 2 = `Settings`
## Graphical User Interface
After starting **AdapterForPdfPid**, the following window appears:
After selecting the input directory and defining the output file, the capture process can begin.
The Excel file named `config.xlsx` must be in the same folder as the imported PDFs.
Start the process by clicking the **Capture** button.
### DocType
AdapterForPdfPid can also be used to convert other PDF drawings, such as equipment arrangement plans or isometric drawings, in order to create semi-intelligent drawings and map them to the 3D model. The document type can be defined in `config.xlsx` in sheet 2. In the example shown here, that sheet is called `Settings`.
For `DocType`, any name can be chosen. Please note that `IntelliPID` is a protected term. Therefore, the IntelliPID sketching module is available only for this document type. If no `DocType` is set in the `Settings` sheet, the documents in this folder are treated automatically as IntelliPID. If no `Settings` sheet exists in `config.xlsx`, the documents in this folder are also treated automatically as IntelliPID.
The PDF file containing the specific drawing type should be a **single-page** document. Otherwise, it is treated as `DocType "IntelliPID"`.
### IgnoreZone
By defining an ignore zone, you can exclude text recognition by AdapterForPdfPid. Text labels within the defined zone are ignored. This can be useful, for example, when excluding text recognition in the title block of a drawing.
### Example PDF P&ID
The following images show the process that **AdapterForPdfPid** follows to generate semi-intelligent P&IDs.
Example input PDF with tank, pumps, valves, lines, and additional information:
Extract from the resulting `config.xlsx` file. This Excel file contains the relevant data to be collected from several input PDFs.
The information is based on regular expressions (`regex`).
### Builder
When viewed in [**IntelliPID**](https://help.caxperts.com/UDiTH%20App/IntelliPID%20Module), the result shows the full graphical representation and also indicates that the main text labels are recognised as intelligent objects.
In the following example, the semi-intelligent information is marked yellow.
For detailed information about 3D/P&ID object linking by using mapping files, see the [Builder documentation](https://help.caxperts.com/UDiTH%20Capture%20Station/Builder#pid-3d-mapping). Additional attributes can also be loaded by using the Builder plugin [ExcelImportPlugin](https://help.caxperts.com/UDiTH%20Capture%20Station/ExcelImportPlugin).
---
# UDiTH Capture Station — SDK
# SDK
The **SDK for UDiTH Builder** allows you to create custom plugins that are executed by **UDiTH Builder**.
With these plugins, you can create new attributes and graphics, or read, update, and delete existing ones.
## Working with SDK for UDiTH Builder
### Creating plugins
To develop a custom plugin, you first need to reference the `UDiTHBuilderPlugin.dll` file in your plugin project. Your custom plugin class must implement the `IPluginVersion1` interface and its `BeforeExport` method. This method is then called by UDiTH Builder.
The `PreExportHook` object that is passed as a parameter to `BeforeExport` is the single entry point. It contains various accessors and methods that allow you to create or modify attributes and graphics dynamically. See the API documentation below for details.
## Prerequisites for debugging
If you want to debug your custom plugin, you must adjust both the **Start Action** and the **Build Events** of your project:
### Start action
Enter the path to your `UDiTH Builder` executable file, for example `%ProgramFiles%\CAXperts\UDiTH Builder\UDiTH Builder.exe`.
### Build events
Under **Post-Build Events**, enter the following:
`COPY /Y "$(TargetPath)" "%AppData%\CAXperts\UDiTH Builder\Plugins"`
This is required because UniversalPlantViewer Builder executes every DLL found in the `%AppData%\CAXperts\UDiTH Builder\Plugins` directory.
### Dependencies
If your plugin requires third-party dependencies or other DLL files, you must place them inside a `libs` folder next to your custom plugin DLL files.
### Running your plugins
Once you have deployed your custom plugin DLLs to the folder in which the SDK looks for plugins, `%AppData%\CAXperts\UDiTH Builder\Plugins`, you can select the plugins to be executed in **Settings -> Plugins**:
### API
The various accessors described below can be accessed through the `PreExportHook` object that is passed as a parameter to the `BeforeExport` method. The `BeforeExport` method is the single entry point for a custom plugin. A plugin class must implement the `IPluginVersion1` interface and its `BeforeExport` method. This method is then called by the SDK in UDiTH Builder.
#### BuilderContext
The builder context is used for writing log information to the UDiTH Builder output file.
#### void Log
(string message)
Writes a message to the UDiTH Builder output file. Requires a `string` message parameter and returns `void`.
#### void LogError
(string message, Exception e)
Writes a message and an exception to the UDiTH Builder output file. Requires a `string` message and an `Exception` object as parameters and returns `void`.
#### void CancelExecution()
Throws a new `CanceledExecutionException`.
#### void CancelExecution
(string message)
Throws a new `CanceledExecutionException` with the specified message. Requires a `string` message parameter.
#### BuilderElementAccessor
This accessor contains methods for accessing elements and session objects.
#### IEnumerable\| Class | Description |
|---|---|
| [CanceledExecutionException](#canceledexecutionexception-class) | - |
| Structure | Description |
|---|---|
| [Color](#color-structure) | - |
| [Vector3D](#vector3d-structure) | - |
| Interface | Description |
|---|---|
| [IBuilderAttributeAccessor](#ibuilderattributeaccessor-interface) | Exposes methods to modify the internal attributes Notes: AttributeNames are treated case insensitive. |
| [IBuilderContext](#ibuildercontext-interface) | Exposes general builder methods. |
| [IBuilderDocumentAccessor](#ibuilderdocumentaccessor-interface) | Exposes methods to manipulate documents shown in the tree (currently Docs only, 2D/PID might follow in the future). |
| [IBuilderElementAccessor](#ibuilderelementaccessor-interface) | - |
| [IBuilderElementAccessor](#ibuilderelementaccessor-interface) | - |
| [IBuilderGraphicAccessor](#ibuildergraphicaccessor-interface) | - |
| [IBuilderIntelliPidAttributeAccessor](#ibuilderintellipidattributeaccessor-interface) | Exposes methods to modify the internal attributes Notes: AttributeNames are treated case insensitive |
| [IBuilderIntelliPidElementAccessor](#ibuilderintellipidelementaccessor-interface) | - |
| [IBuilderLinkAccessor](#ibuilderlinkaccessor-interface) | - |
| [IDocument](#idocument-interface) | - |
| [IElement](#ielement-interface) | - |
| [IGraphicElement](#igraphicelement-interface) | - |
| [IIntelliPidElement](#iintellipidelement-interface) | - |
| [ILink](#ilink-interface) | - |
| [IPluginVersion1](#ipluginversion1-interface) | - |
| [IPreExportHook](#ipreexporthook-interface) | - |
| [ISession](#isession-interface) | - |
| [ISessionTransformation](#isessiontransformation-interface) | - |
| Enumeration | Description |
|---|---|
| [LinkType](#linktype-enumeration) | - |
| Name | Description |
|---|---|
| [CanceledExecutionException()](#canceledexecutionexception-constructor-1) | Initializes a new instance of the **CanceledExecutionException** class. |
| [CanceledExecutionException(String)](#canceledexecutionexception-constructor-string) | Initializes a new instance of the **CanceledExecutionException** class |
| [CanceledExecutionException(String, Exception)](#canceledexecutionexception-constructor-string-exception) | Initializes a new instance of the **CanceledExecutionException** class |
| Name | Description |
|---|---|
| [CanceledExecutionException()](#canceledexecutionexception-constructor-1) | Initializes a new instance of the [CanceledExecutionException](#canceledexecutionexception-class) class |
| [CanceledExecutionException(String)](#canceledexecutionexception-constructor-string) | Initializes a new instance of the [CanceledExecutionException](#canceledexecutionexception-class) class |
| [CanceledExecutionException(String, Exception)](#canceledexecutionexception-constructor-string-exception) | Initializes a new instance of the [CanceledExecutionException](#canceledexecutionexception-class) class |
| Name | Description |
|---|---|
| [A](#color.a-property) | - |
| [B](#color.b-property) | - |
| [G](#color.g-property) | - |
| [R](#color.r-property) | - |
| Name | Description |
|---|---|
| [AddAttribute](#ibuilderattributeaccessor.addattribute-method) | Add a new attribute to an element. |
| [DeleteAttribute(String)](#ibuilderattributeaccessor.deleteattribute-method-string) | Completely remove an attribute. |
| [DeleteAttribute(IElement, String)](#ibuilderattributeaccessor.deleteattribute-method-ielement-string) | Remove attribute from element. |
| [DeleteElement](#ibuilderattributeaccessor.deleteelement-method) | **Obsolete.** Fully delete an element (mesh and attributes) |
| [FindElementsByAttributes](#ibuilderattributeaccessor.findelementsbyattributes-method) | Find all elements by condition |
| [GetAttributes](#ibuilderattributeaccessor.getattributes-method) | Extract all attribute values of an element. |
| [GetElement](#ibuilderattributeaccessor.getelement-method) | **Obsolete.** Access a single element |
| [IterateAttributes](#ibuilderattributeaccessor.iterateattributes-method) | Iterate over all attribute keys. |
| [IterateElements](#ibuilderattributeaccessor.iterateelements-method) | **Obsolete.** Iterate over all elements |
| [RenameAttribute(String, String)](#ibuilderattributeaccessor.renameattribute-method-string-string) | Change an attribute key for all elements. |
| [RenameAttribute(IElement, String, String)](#ibuilderattributeaccessor.renameattribute-method-ielement-string-string) | Rename existing attribute in element. |
| [UpdateAttribute](#ibuilderattributeaccessor.updateattribute-method) | Update existing attribute in element. |
| Name | Description |
|---|---|
| [DeleteAttribute(String)](#ibuilderattributeaccessor.deleteattribute-method-string) | Completely remove an attribute |
| [DeleteAttribute(IElement, String)](#ibuilderattributeaccessor.deleteattribute-method-ielement-string) | Remove attribute from element |
| Name | Description |
|---|---|
| [RenameAttribute(String, String)](#ibuilderattributeaccessor.renameattribute-method-string-string) | Change an attribute key for all elements. |
| [RenameAttribute(IElement, String, String)](#ibuilderattributeaccessor.renameattribute-method-ielement-string-string) | Rename existing attribute in element. |
| Name | Description |
|---|---|
| [CancelExecution()](#ibuildercontext.cancelexecution-method-1) | Cancel execution |
| [CancelExecution(String)](#ibuildercontext.cancelexecution-method-string) | Cancel execution and print to the UPVB output file |
| [Log](#ibuildercontext.log-method) | Print to the UPVB output file |
| [LogError](#ibuildercontext.logerror-method) | Print an exception stacktrace to the UPVB output file |
| Name | Description |
|---|---|
| [CancelExecution()](#ibuildercontext.cancelexecution-method-1) | Cancel execution |
| [CancelExecution(String)](#ibuildercontext.cancelexecution-method-string) | Cancel execution and print to the UPVB output file |
| [Log](#ibuildercontext.log-method) | Print to the UPVB output file |
| [LogError](#ibuildercontext.logerror-method) | Print an exception stacktrace to the UPVB output file |
| Name | Description |
|---|---|
| [CancelExecution()](#ibuildercontext.cancelexecution-method-1) | Cancel execution |
| [CancelExecution(String)](#ibuildercontext.cancelexecution-method-string) | Cancel execution and print to the UPVB output file |
| Name | Description |
|---|---|
| [AddRelation](#ibuilderdocumentaccessor.addrelation-method) | Link an element to a created document |
| [CreatePdf](#ibuilderdocumentaccessor.createpdf-method) | Register a new pdf file which will be written to the general output location |
| Name | Description |
|---|---|
| [AddRelation](#ibuilderdocumentaccessor.addrelation-method) | Link an element to a created document |
| [CreatePdf](#ibuilderdocumentaccessor.createpdf-method) | Register a new pdf file which will be written to the general output location |
| Name | Description |
|---|---|
| [Sessions](#ibuilderelementaccessor.sessions-property) | - |
| Name | Description |
|---|---|
| [CreateElement](#ibuilderelementaccessor.createelement-method) | Create a new builder element |
| [DeleteElement](#ibuilderelementaccessor.deleteelement-method) | Fully delete an element (mesh and attributes) |
| [GetElement](#ibuilderelementaccessor.getelement-method) | Access a single element |
| [IterateElements](#ibuilderelementaccessor.iterateelements-method) | Iterate over all elements |
| Name | Description |
|---|---|
| [Sessions](#ibuilderelementaccessor.sessions-property) |
| Name | Description |
|---|---|
| [CreateElement](#ibuilderelementaccessor.createelement-method) | Create a new builder element |
| [DeleteElement](#ibuilderelementaccessor.deleteelement-method) | Fully delete an element (mesh and attributes) |
| [GetElement](#ibuilderelementaccessor.getelement-method) | Access a single element |
| [IterateElements](#ibuilderelementaccessor.iterateelements-method) | Iterate over all elements |
| Name | Description |
|---|---|
| [CreateAspect](#ibuildergraphicaccessor.createaspect-method) | Create a new aspect |
| [CreateGraphic](#ibuildergraphicaccessor.creategraphic-method) | Create a new graphic object |
| [DeleteAspect](#ibuildergraphicaccessor.deleteaspect-method) | Delete an existing aspect |
| [GetAspects](#ibuildergraphicaccessor.getaspects-method) | Get all aspects |
| [GetGraphics](#ibuildergraphicaccessor.getgraphics-method) | Get all graphic objects of an element |
| [GetPrimitives](#ibuildergraphicaccessor.getprimitives-method) | Get primitives of a graphic element |
| [GetSessionTransformation](#ibuildergraphicaccessor.getsessiontransformation-method) | Get transformation object for the corresponding session |
| [SetColor](#ibuildergraphicaccessor.setcolor-method) | Set the color of a graphic element |
| [SetPrimitives](#ibuildergraphicaccessor.setprimitives-method) | Set primitives of a graphic element |
| Name | Description |
|---|---|
| [CreateAspect](#ibuildergraphicaccessor.createaspect-method) | Create a new aspect |
| [CreateGraphic](#ibuildergraphicaccessor.creategraphic-method) | Create a new graphic object |
| [DeleteAspect](#ibuildergraphicaccessor.deleteaspect-method) | Delete an existing aspect |
| [GetAspects](#ibuildergraphicaccessor.getaspects-method) | Get all aspects |
| [GetGraphics](#ibuildergraphicaccessor.getgraphics-method) | Get all graphic objects of an element |
| [GetPrimitives](#ibuildergraphicaccessor.getprimitives-method) | Get primitives of a graphic element |
| [GetSessionTransformation](#ibuildergraphicaccessor.getsessiontransformation-method) | Get transformation object for the corresponding session |
| [SetColor](#ibuildergraphicaccessor.setcolor-method) | Set the color of a graphic element |
| [SetPrimitives](#ibuildergraphicaccessor.setprimitives-method) | Set primitives of a graphic element |
| Name | Description |
|---|---|
| [AddAttribute](#ibuilderintellipidattributeaccessor.addattribute-method) | Add a new attribute to an element |
| [DeleteAttribute(String)](#ibuilderintellipidattributeaccessor.deleteattribute-method-string) | Completely remove an attribute |
| [DeleteAttribute(IIntelliPidElement, String)](#ibuilderintellipidattributeaccessor.deleteattribute-method-iintellipidelement-string) | Remove attribute from element |
| [FindElementsByAttributes](#ibuilderintellipidattributeaccessor.findelementsbyattributes-method) | Find all elements by condition |
| [GetAttributes](#ibuilderintellipidattributeaccessor.getattributes-method) | Extract all attribute values of an element |
| [IterateAttributes](#ibuilderintellipidattributeaccessor.iterateattributes-method) | Iterate over all attribute keys |
| [RenameAttribute(String, String)](#ibuilderintellipidattributeaccessor.renameattribute-method-string-string) | Change an attribute key for all elements |
| [RenameAttribute(IIntelliPidElement, String, String)](#ibuilderintellipidattributeaccessor.renameattribute-method-iintellipidelement-string-string) | Rename existing attribute in element |
| [UpdateAttribute](#ibuilderintellipidattributeaccessor.updateattribute-method) | Update existing attribute in element |
| Name | Description |
|---|---|
| [AddAttribute](#ibuilderintellipidattributeaccessor.addattribute-method) | Add a new attribute to an element |
| [DeleteAttribute(String)](#ibuilderintellipidattributeaccessor.deleteattribute-method-string) | Completely remove an attribute |
| [DeleteAttribute(IIntelliPidElement, String)](#ibuilderintellipidattributeaccessor.deleteattribute-method-iintellipidelement-string) | Remove attribute from element |
| [FindElementsByAttributes](#ibuilderintellipidattributeaccessor.findelementsbyattributes-method) | Find all elements by condition |
| [GetAttributes](#ibuilderintellipidattributeaccessor.getattributes-method) | Extract all attribute values of an element |
| [IterateAttributes](#ibuilderintellipidattributeaccessor.iterateattributes-method) | Iterate over all attribute keys |
| [RenameAttribute(String, String)](#ibuilderintellipidattributeaccessor.renameattribute-method-string-string) | Change an attribute key for all elements |
| [RenameAttribute(IIntelliPidElement, String, String)](#ibuilderintellipidattributeaccessor.renameattribute-method-iintellipidelement-string-string) | Rename existing attribute in element |
| [UpdateAttribute](#ibuilderintellipidattributeaccessor.updateattribute-method) | Update existing attribute in element |
| Name | Description |
|---|---|
| [DeleteAttribute(String)](#ibuilderintellipidattributeaccessor.deleteattribute-method-string) | Completely remove an attribute |
| [DeleteAttribute(IIntelliPidElement, String)](#ibuilderintellipidattributeaccessor.deleteattribute-method-iintellipidelement-string) | Remove attribute from element |
| Name | Description |
|---|---|
| [RenameAttribute(String, String)](#ibuilderintellipidattributeaccessor.renameattribute-method-string-string) | Change an attribute key for all elements |
| [RenameAttribute(IIntelliPidElement, String, String)](#ibuilderintellipidattributeaccessor.renameattribute-method-iintellipidelement-string-string) | Rename existing attribute in element |
| Name | Description |
|---|---|
| [Sessions](#ibuilderintellipidelementaccessor.sessions-property) |
| Name | Description |
|---|---|
| [GetElement](#ibuilderintellipidelementaccessor.getelement-method) | Access a single element |
| [IterateElements](#ibuilderintellipidelementaccessor.iterateelements-method) | Iterate over all elements |
| Name | Description |
|---|---|
| [Sessions](#ibuilderintellipidelementaccessor.sessions-property) |
| Name | Description |
|---|---|
| [GetElement](#ibuilderintellipidelementaccessor.getelement-method) | Access a single element |
| [IterateElements](#ibuilderintellipidelementaccessor.iterateelements-method) | Iterate over all elements |
| Name | Description |
|---|---|
| [AddRelation](#ibuilderlinkaccessor.addrelation-method) | |
| [CreateLink](#ibuilderlinkaccessor.createlink-method) | Create a new link - Use the returned identifier to register elements to the link |
| Name | Description |
|---|---|
| [AddRelation](#ibuilderlinkaccessor.addrelation-method) | |
| [CreateLink](#ibuilderlinkaccessor.createlink-method) | Create a new link - Use the returned identifier to register elements to the link |
| Name | Description |
|---|---|
| [Session](#ielement.session-property) | |
| [Uid](#ielement.uid-property) |
Name |
Description |
|
|---|---|---|
Obsolete. Add a new attribute to an element |
||
Obsolete. Remove attribute from element |
||
Obsolete. Extract all attribute values of an element |
||
Obsolete. Rename existing attribute in element |
||
Obsolete. Update existing attribute in element |
| Name | Description |
|---|---|
| [AddAttribute](#ielement.addattribute-method) | **Obsolete.** Add a new attribute to an element |
| [DeleteAttribute](#ielement.deleteattribute-method) | **Obsolete.** Remove attribute from element |
| [GetAttributes](#ielement.getattributes-method) | **Obsolete.** Extract all attribute values of an element |
| [RenameAttribute](#ielement.renameattribute-method) | **Obsolete.** Rename existing attribute in element |
| [UpdateAttribute](#ielement.updateattribute-method) | **Obsolete.** Update existing attribute in element |
| Name | Description |
|---|---|
| [AspectName](#igraphicelement.aspectname-property) | |
| [ParentElement](#igraphicelement.parentelement-property) |
| Name | Description |
|---|---|
| [AspectName](#igraphicelement.aspectname-property) | |
| [ParentElement](#igraphicelement.parentelement-property) |
| Name | Description |
|---|---|
| [Session](#iintellipidelement.session-property) | |
| [Uid](#iintellipidelement.uid-property) |
| Name | Description |
|---|---|
| [Session](#iintellipidelement.session-property) | |
| [Uid](#iintellipidelement.uid-property) |
| Name | Description |
|---|---|
| [Name](#ipluginversion1.name-property) | |
| [ProcessOrder](#ipluginversion1.processorder-property) |
| Name | Description |
|---|---|
| [BeforeExport](#ipluginversion1.beforeexport-method) |
| Name | Description |
|---|---|
| [Name](#ipluginversion1.name-property) | |
| [ProcessOrder](#ipluginversion1.processorder-property) |
| Name | Description |
|---|---|
| [BeforeExport](#ipluginversion1.beforeexport-method) |
| Name | Description |
|---|---|
| [BuilderAttributeAccessor](#ipreexporthook.builderattributeaccessor-property) | |
| [BuilderContext](#ipreexporthook.buildercontext-property) | |
| [BuilderDocumentAccessor](#ipreexporthook.builderdocumentaccessor-property) | |
| [BuilderElementAccessor](#ipreexporthook.builderelementaccessor-property) | |
| [BuilderGraphicAccessor](#ipreexporthook.buildergraphicaccessor-property) | |
| [BuilderIntelliPidAttributeAccessor](#ipreexporthook.builderintellipidattributeaccessor-property) | |
| [BuilderIntelliPidElementAccessor](#ipreexporthook.builderintellipidelementaccessor-property) | |
| [BuilderLinkAccessor](#ipreexporthook.builderlinkaccessor-property) |
| Name | Description |
|---|---|
| [BuilderAttributeAccessor](#ipreexporthook.builderattributeaccessor-property) | |
| [BuilderContext](#ipreexporthook.buildercontext-property) | |
| [BuilderDocumentAccessor](#ipreexporthook.builderdocumentaccessor-property) | |
| [BuilderElementAccessor](#ipreexporthook.builderelementaccessor-property) | |
| [BuilderGraphicAccessor](#ipreexporthook.buildergraphicaccessor-property) | |
| [BuilderIntelliPidAttributeAccessor](#ipreexporthook.builderintellipidattributeaccessor-property) | |
| [BuilderIntelliPidElementAccessor](#ipreexporthook.builderintellipidelementaccessor-property) | |
| [BuilderLinkAccessor](#ipreexporthook.builderlinkaccessor-property) |
| Name | Description |
|---|---|
| [SessionFile](#isession.sessionfile-property) |
| Name | Description |
|---|---|
| [SessionFile](#isession.sessionfile-property) |
| Name | Description |
|---|---|
| [Rotation](#isessiontransformation.rotation-property) | |
| [Scale](#isessiontransformation.scale-property) | |
| [Source](#isessiontransformation.source-property) | |
| [Translation](#isessiontransformation.translation-property) |
| Name | Description |
|---|---|
| [Rotation](#isessiontransformation.rotation-property) | |
| [Scale](#isessiontransformation.scale-property) | |
| [Source](#isessiontransformation.source-property) | |
| [Translation](#isessiontransformation.translation-property) |
| Member name | Value | Description |
|---|---|---|
| **Default** | 0 | No special treatment |
| **Pdf** | 1 | Opens the embedded pdf viewer with the link content |
| **Event** | 2 | Only triggers the api event. Will not open the link |
| Name | Description |
|---|---|
| [X](#vector3d.x-property) | |
| [Y](#vector3d.y-property) | |
| [Z](#vector3d.z-property) |
| Name | Description |
|---|---|
| [X](#vector3d.x-property) | |
| [Y](#vector3d.y-property) | |
| [Z](#vector3d.z-property) |
Select a sketching object from the right-hand menu and place it within the laser scan object. Most commonly, a box or a horizontal or vertical vessel is used to define a clipping box or clipping volume.
After the sketch has been placed, the sketching object can be moved, resized, or rotated about the Z-axis to match the required clipping result. The sketching objects can also be colourised, and their transparency can be adjusted to make identification and orientation easier.
## Clipping Attributes
To define a sketching object as a clipping object, select the sketch object and use the drop-down list for the **LaserScanClippingMode** attribute. The default value, **Ignore**, means that the object is not used for clipping.
## LaserScanClippingMode -- ClipOutside
With the **OuterBound** value set, everything **outside** this boundary item is cut away from the laser scan. Any other 3D data or sketches are not affected. This is useful, for example, when there are superficial parts outside the main target area of the laser scan that are considered irrelevant and should be removed.
Place a sketch item of type `box`, then move and scale it to cover the area you want to keep. In this example, the bounding box is coloured white and set to semi-transparent so that it remains visible while still allowing you to see through it.
After saving the sketch as a `.upvc` file and building it with UniversalPlantViewer Builder, only the laser scan elements within the clipping box remain.
## LaserScanClippingMode -- Isolate
With the **Isolate** value set, you can use different items to define a shape that is converted into an independent object as accurately as possible. This is useful, for example, if you want to isolate a pump from the laser scan and make it into a separate object.
Place the sketch items, then move and scale them so that they cover the volume belonging to the required item. The colour used for the sketching items becomes the colour assigned to the object after clipping.
When the sketch is saved as a `.upvc` file, the laser scan data located inside the shapes is cut from the laser scan and replaced by a separate object when the model is rebuilt with UniversalPlantViewer Builder. These objects can then be recoloured, hidden, or found individually through the search function by using their attributes.
The isolated objects can be given additional custom attributes. These attributes remain part of the object even after clipping, making it possible to attach data, links, and similar information to the resulting object. See the UniversalPlantViewer documentation for more information about custom attributes.
## LaserScanClippingMode -- Delete
With the **Delete** value set, everything inside this boundary item is cut out of the laser scan. Any other 3D data or sketches are not affected. This is useful, for example, when people moved through the laser scan and left artefacts that need to be removed.
Place a sketch item, then move and scale it to cover the volume you want to remove. In this example, the bounding box is coloured red and set to semi-transparent so that it can still be seen through.
When the sketch is saved as a `.upvc` file, the laser scan data located inside the shapes is cut from the laser scan when the model is rebuilt with UniversalPlantViewer Builder.
## LaserScanClippingMode -- Update
By using the value **Update**, specific parts of a laser scan can be committed to an existing laser scan, while the rest of the older scan remains unchanged.
To do this, the `UPVBPluginLaserscanClipping.xml` file must be edited.
The file can be found at:
`AppData\Roaming\CAXperts\Universal Plant Viewer Builder\Plugins\UPVBPluginLaserscanClipping.xml`
The tag `UpdateOldUPVC` must contain the name of the `.upvc` file for the model to be updated. `UpdateNewUPVC` must contain the name of the newer `.upvc` file containing the update-marked clipped objects. When these two files are built in UniversalPlantViewer Builder, the older model contains the clipped parts as they appear in the newer version, while the rest of the model remains unchanged.
## Save Sketch Definitions
It is strongly recommended to save the sketch definitions as UPV Sketch files (`.upvf`). This is not required for clipping, but it allows you to recall the sketch definitions, load them into later models, or edit them afterwards.
## Export Clipping Definitions
To use the clipping sketches you have created for the actual clipping process, the files must be saved as UPV core files (`.upvc`) for use with UniversalPlantViewer Builder. Make sure that `.upvc` is selected as the save format and that the files are saved in the same folder as the original source files used to build the model.
## UniversalPlantViewer Builder settings
To create the final clipped laser scan model, you must run UniversalPlantViewer Builder so that it can execute the clipping tasks defined by the clipping sketch items. To do this, start UPV Builder and click the **[Browse...]** button.
## Selecting Sessions
In the following file-open dialogue, select the original laser scan session and all clipping sessions that you want to integrate into the new model (`.upvc` files) while holding down the **Ctrl** key, then confirm by clicking **[Open]**.
A new dialogue appears, asking for a file name for saving the collection of multiple session files (`.upvm`). Enter a file name that you will recognise later.
## Activating the LaserscanClippingPlugin
For clipping to work, LaserscanClippingPlugin must first be activated. Go to **Tools → Settings** in the menu bar and select the **Plugins** tab.
Select the `UPVPluginLaserscanClipping` plugin from the available plugins, move it to the used plugins by clicking **[>]**, and confirm the selection with **[OK]**.
## Selecting additional Attributes
To integrate additional attributes, they must first be activated. Otherwise, they are ignored when the final clipped model is created. Go to **Tools → Settings** in the menu bar and select the **Attributes** tab. Select the attributes you want to use from the available attributes, move them to the used attributes by clicking **[>]**, and confirm the selection with **[OK]**.
## Output
Run UniversalPlantViewer Builder as usual. The resulting UPV contains the final clipped model.
---
# UDiTH Capture Station — ExcelImportPlugin
# ExcelImportPlugin
The **ExcelImportPlugin** is used to sideload additional attribute data not included in the initial source files. This feature helps to implement data from sources other than the original authoring systems and can contain any information, e.g. from third-party-sources or databases.
## Setup Procedure
The **ExcelImportPlugin** is not an executable plugin and comes without a setup routine. After the file download, unpack the content of the container (.zip) to **one** of the directories listed.
For current user use only:
%AppData%\\CAXperts\\UDiTH Builder\\Plugins\\
For all users (administrator rights might be required):
%programfiles%\\CAXperts\\UDiTH Builder\\Plugins\\
## Usage
## Attribute and Value Definition
The Attributes are defined in an Excel file following a fixed syntax:
**Source Attribute (UPVC)** -- The Source Attribute to look for when adding a new attribute.
**Source Value (UPVC)** -- Specifies a condition for the Source Attribute value.
**New Attribute** -- The new attribute you wish to define.
**New Value** -- The value to be stored under the new attribute.
By choosing a Source Attribute that applies to multiple objects, the new attribute is added to all objects containing that attribute with the defined Source Value.
Further **New Attribute** and **New Value** can be added to import multiple attributes
For importing attributes to IntelliPID the sheet in the Excel file needs to be named "IntelliPID_Import", for 3D the sheet should be called "Import".
## File Name and Placement
Multiple Excel files are supported. The ExcelImportPlugin will consume all Excel files within the "ExcelImport" folder next to the selected UPVC/UPVM file.
> This folder must be placed in the directory containing your .upvc files.
If this is the case, the files in the folder will automatically be considered once the plugin is activated in the UDiTH Builder
If the folder is not present, the file defined in the configuration file will be used. If that file is not found, either, the plugin will be ignored in the building process.
## Activating the ExcelImportPlugin
To import the additional attributes and values, the ExcelImport Plugin must be activated first. Go to **Tools → Settings** in the menu bar and select the **Plugins** tab. Select the "UPVPluginExcelImport" plugin from available plugins (fig. 2-1), transfer it to the used plugins by clicking on the **\[\>\]** button (fig. 2-2) and confirm your selection with **\[OK\]** (fig. 2-3).
## Configuration File
The plugin is configurable through a configuration file named UPVPluginExcelImport.xml. This file is located alongside the .dll of the plugin (see chapter "Setup procedure"). It contains three values that can be set for configuration (fig. 3).
```xml
| Field | Description |
|---|---|
| Alias | Identifies the provider. This value can be chosen freely. |
| Discovery endpoint |
Path to the `.well-known/openid-configuration`, for example for Azure ADFS: `https://login.microsoftonline.com/ |
| Client ID | Obtained from the Azure app registration. |
| Client Secret | Can be generated in the Azure app registration under **Manage / Certificates & secrets**. |
| Advanced/Backchannel logout (optional) | Recommended value: **true**. This ensures that logging out of UDiTH Portal does not also log the user out of the identity provider. |
2. Set up a new app registration in Microsoft Azure.
The **Redirect URI** can be copied from the first field entry in the Keycloak registration, for example `http://localhost:8080/realms/uws/broker/oidc/endpoint`. Enter it in the **Redirect URI** field of the Azure app registration.
3. Configure API permissions.
On the Azure API permissions page, add `email`, `openid`, `profile`, and `User.Read` as delegated Microsoft Graph permissions.
4. Try logging in to UDiTH Portal.
There should now be a new sign-in option in the Keycloak login screen.
## Additional configuration options
### Use group synchronization
Allow UDiTH Portal to extract user groups from the external provider. The user groups are synchronised when UDiTH Portal is restarted or when **ForceRefresh** is called in the Admin UI.
Create the groups to be synchronised in UDiTH Portal at `../administration/groups`.
Assign the **Group GUID** found in Azure Portal to the new group. The group connection is established by using this GUID value.
Allow the group claim to be requested in Azure Portal:
On the **Token Configuration** page:
- add an additional `groups` claim.
Relevant for Keycloak major version 25 and later:
Create the `groups` attribute, as unmanaged attributes are no longer allowed by default.
To do this, go to **Realm Settings / User profile** and create an attribute named **groups**.
In the Keycloak **Identity provider** settings, add a new entry under **Mappers**.
This transmits the information from the **groups** claim to the user's attribute field. UDiTH Portal expects the **User attribute name** to be set to **groups**.
If your identity provider uses a different group claim name, you can define the required **Claim** name in this mapper. Note that the **Claim** value is case-sensitive.
**Sync mode** defines when the mapper is executed.
Options:
- **Force**: Updates on every login. Recommended.
- **Import**: Updates only when the user is created in Keycloak for the first time.
### Import roles
You can also use a new **Mappers** entry for this.
This is done by using the **Claim to Role** mapper.
### Metadata customization
You can also use a new **Mappers** entry for this.
This is done by providing the required **User attributes**. Relevant predefined mappers for this use case are **Attribute Importer** and **Hardcoded Attribute**.
For example, if you provide a user attribute named **email**, this corresponds to the user's email entry.
Keycloak claims:
- username
- firstName
- lastName
- email
- emailVerified, which does not appear to work at the moment
### Troubleshooting
You can use the following Keycloak start command to enable logging of user claims during sign-in:
`kc.bat start --log-level="INFO,org.keycloak.social.user_profile_dump:debug"`
---
# UDiTH Portal — Advanced integration options
# Advanced integration options
There are multiple flexible options for integrating your product with UDiTH Portal.
Code examples are available at:
After calling `ForceSynchronize` on the UDiTH Portal application side, this account is also available in the UDiTH Portal admin UI.
Here, you can configure the fine-grained access rights for the account.
The user group can then be assigned permissions for specific models.
#### How to create a service account
- Open the Keycloak URL.
- Go to **Administration Console**.
- Sign in by using a Keycloak admin account. If you are not self-hosting the Keycloak server, contact your hosting provider and ask them to provide an admin account.
- Make sure that your application realm is selected. The realm name is configurable during installation. The `master` realm must never be used. When using a hosting provider, this realm may be named differently.
- Go to **Clients** in the left-hand menu. Service accounts are directly associated with an OpenID Connect client entry.
- Click **Create client**.
- Choose any value for **Client ID** and click **Next**.
- On the **Capability config** step, apply the following settings (shown in the image above):
- **Client authentication**: **On**
- **Authorization**: **Off**
- **Authentication flow**: enable **Standard flow**, **Direct access grants**, and — most importantly — **Service accounts roles**.
The **Service accounts roles** option is responsible for associating a new service account with the client and must be enabled for machine-to-machine authentication. You can, of course, change these settings if you have specific authentication requirements.
- Click **Next**.
- Leave **Login settings** unchanged and save the client.
- The client automatically receives a client secret, that is, a password. You can access it on the **Credentials** tab of the client.
- The generated Keycloak service account can be viewed on the client page under the **Service accounts roles** tab.
---
# UDiTH Portal — Secure Setup Guidelines
# Secure Setup Guidelines
This page describes the recommended way to operate UDiTH Portal with a small
attack surface. It is a hardening guide, not an installation guide. For the
installation steps, see [Setup Portal Linux](/UDiTH%20Portal/Setup%20Portal%20Linux)
and [Requirements](/UDiTH%20Portal/Requirements).
## Summary
| Topic | Recommendation |
| ---------------- | ----------------------------------------------------------- |
| Platform | Linux with Docker (or Podman) |
| Image variant | `ubuntu-chiseled` |
| Isolation | `cap_drop: ALL`, `no-new-privileges`, AppArmor profile |
| Transport | HTTPS only, legacy TLS protocols switched off |
| External access | Reverse proxy, Caddy or the product of your choice |
| Secrets | Azure Key Vault, or Docker secrets |
| Maintenance | Keep the host and all applications up to date |
## Use Linux
Run Portal on Linux in containers. A container gives you process, file system
and network isolation that the Windows installation on IIS cannot provide.
- Use a supported LTS distribution.
- Install only the packages that the container runtime needs.
- Keep the Docker daemon and the container runtime current.
## Use the `ubuntu-chiseled` Image
The `quay.io/caxperts/portal` image is published in several variants. For a
secure setup, use `ubuntu-chiseled`.
- The chiseled image is a minimal, distroless-style image. It contains **no
shell and no package manager**.
- Without a shell, an attacker who reaches the container has almost no tools
available.
- The image contains fewer packages, so it has fewer known vulnerabilities.
- The container runs as the unprivileged user with uid `1654`, not as `root`.
The other variants (`ubuntu`, `alpine`, `noble`) run as `root` inside the
container. Use them only if you must run commands in the container, for example
for support or diagnostics.
Prepare the bind-mounted volumes for uid `1654`:
```bash
mkdir -p /srv/udith/storage /srv/udith/import /srv/udith/upload
chown -R 1654:1654 /srv/udith/storage /srv/udith/import /srv/udith/upload
chmod -R u+rwX /srv/udith/storage /srv/udith/import /srv/udith/upload
```
For details on the variants, the uids and the volume permissions, see
[Image Variants and Volume Permissions](/UDiTH%20Portal/Setup%20Portal%20Linux#image-variants-and-volume-permissions).
To add your own CA certificates to the chiseled image, see
[Adding Custom CA Certificates](/UDiTH%20Portal/Adding%20Custom%20CA%20Certificates).
### Additional Container Settings
Add the following settings to the Portal service in your `docker-compose.yml`:
```yml
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
```
Notes:
- `read_only` requires that all writable paths are volumes or `tmpfs`. Test this
setting before you use it in production.
- Do not publish the container port to the host. Let the reverse proxy reach the
container over an internal Docker network.
### AppArmor Profile
CAXperts provides an AppArmor profile for the Portal container. The profile
restricts the container to the files, directories and network operations that
Portal actually needs.
> ⚠️ **Important**: The profile is only valid for the `ubuntu-chiseled` variant.
> The other variants have a different file system layout and a different user,
> so the profile does not match them.
Save the profile as `/etc/apparmor.d/docker-portal` on the host:
```
# Last Modified: Tue Jul 7 17:08:13 2026
abi Dear Team,
Ticket #${PunchItem} has been updated.
This is an automated notification from ${serverAddress}
``` **Note:** Subject lines can also use dynamic variable replacement with the same syntax shown above. # Workflows Kanban The **Kanban Settings** page allows administrators to configure the appearance of the Kanban cards that appear in the "**Planning**" section by selecting fields for the title, subtitle, and content zones. These settings impact how information is displayed within the Kanban view, enabling a tailored experience to suit specific workflows.  ## Kanban Settings Actions - **Purpose**: Define what information appears on the Kanban cards for the title, subtitle, and content areas. - **How to Use**: - Open the drop-down menus for **Title**, **Subtitle**, and **Content**. - Select a field from the list of available options, which are fetched from the system’s punch details available fields.  - Each selection updates the Kanban card preview in real time, allowing you to instantly see how your choices affect the card layout. The preview is displayed to the right of the select boxes. - The values from the fields you select in the drop-down menus will automatically populate the corresponding sections of each individual Kanban card.  - After finalizing your selections, click the **Save** button. - A confirmation message will appear, notifying you that the settings have been saved successfully. # Ticket Fields The **Ticket Fields** (also called Punchlist) page allows administrators to add, configure and manage available punchlist fields effectively. These fields define how information is structured and displayed in punchlists, ensuring adaptability to various workflows and requirements.  ## Managing Ticket Fields Administrators can add, edit, delete, and reorder punchlist fields using the following actions. This fields can also be grouped into ticket types. ### Adding a New Ticket Field 1. **Add a Field:** - Click the **Plus (+) button** in the top right corner to add a new punchlist field. 2. **Fill in Field Details:** Fields are accessed by single-clicking on the respective cell. - **Detail (Required):** Enter the name of the punchlist field. - **Type (Required):** Select the field type. See options below. - **dxTextBox:** A textbox for user input of text data. - **dxSelectBox:** A dropdown select box allowing users to choose from predefined options. These options are specified by the administrator in the "**Items**" column. - **dxDateBox:** A date picker for selecting dates. - **dxHyperLink:** A hyperlink element that navigates to a user specified URL. - **Breakline:** Inserts a horizontal line to separate content sections in punchlist user form. - **Additional Options:** - **Column Span:** Specify the number of columns this field should occupy on the punch item's detail page. - **Default View:** Choose whether this field should be displayed by default in the main punchlist table. - **Items (for Selectbox):** If the type is Selectbox, specify the available options in the **Items** column. - **Editors:** Grant the selected roles permission to edit the specified field. The field will be in a read-only state for roles not included in this option.  3. **Save or Revert:** - **Save:** Click the **Save** button at the end of the row to save the new field. - **Revert:** Click the **Revert** button to discard the new entry. ### Editing an Existing Ticket Field - Click the **Pencil icon** at the end of the row corresponding to the field you wish to edit. - Modify the necessary details. - Click **Save** to apply changes or **Revert** to cancel. ### Deleting a Ticket Field - Click the **Trash icon** at the end of the row for the field you want to delete. - **Warning:** Deleted fields cannot be recovered. Confirm the deletion when prompted. ### Reordering Ticket Fields - **Drag and Drop:** - Click and hold the **Six-Dot icon** (⋮⋮) to the left of a row. - Drag the row to your desired position within the table. - Release to drop the row in the new position. - The order of the rows in the table defines the order in which the fields appear in the punchlist user form.  # Attribute Mapping The **Attribute Mapping** section enables administrators to define relationships between ticket detail fields and model attributes. These mappings are applied to the comments of ticket items that are created using the "**Create with Comment**" option in main tickets table.  ## Features ### 1. Mapping Interface Overview - **Punch Details List**: Displays un-mapped ticket details available for mapping. - **Mapped Attributes List**: Lists existing mappings with details such as the mapped attribute(s) and type (2D, 3D, or Code). ### 2. Mapping Actions **Add Detail to Mapping** 1. Click the "+" button to move the detail to the mapped attributes list. 2. The detail is now ready to be mapped to an attribute. 3. Select up to 3 ticket details to generate a custom ticket comment.  **Map Attribute to Detail** - In the **Mappings** pane click the **Edit** button of the field you would like to map an attribute to. - This will open a pop-up that has options to either map to a 3D, 2D or custom code attribute. - Click on any of these options to choose a mapping type: - **3D Single Mapping**: Map the field to a 3D attribute. A list is available for the administrator to select from which contains all possible model attributes. - **2D Single Mapping**: Map the field to a 2D attribute. These attributes can be user-defined in the textbox. - **Code Mapping**: Map the field using a [Custom Code](#custom-code) - Save changes to finalize the mapping.  Creating a ticket with the option "Create with Comment" now reflect changes made with regards to attribute mapping:  **Delete Mapping** - Click the **Trash** button next to a mapped attribute to remove the mapping. - The detail returns to the **Ticket Details** list for future use. # Event Listeners The **Event Listeners** section provides administrators with tools to manage event-driven automation throughout the Toolkit application. Event listeners enable custom actions or behaviors triggered by specific conditions, such as field value changes, workflow actions, ticket creation, email sending, or scheduled intervals. Unlike [Field Validators](#field-validators) which **prevent** invalid data from being saved, event listeners **react** to events after they occur, executing custom code to automate workflows, send notifications, update related fields, or trigger external integrations.  ## Understanding Listener Types Each listener must have a **Type** that determines when and how it triggers. The listener's required fields vary based on the selected type. Administrators must select the appropriate type and configure type-specific fields to create functional listeners. > **Important — a listener runs only once per ticket.** After a listener has run for a ticket, it does not run for that ticket again, even if its condition becomes true again later (for example, the same step is accepted a second time, or the ticket is overdue on the next check). The run is recorded even if the custom code fails. `onEmailReceived` and `onInteractionEmailSent` listeners are the exception: they run for every matching email. ### Available Listener Types #### 1. onWorkflowStepAccepted **Description:** Triggers when a specific workflow step is accepted by a user. **When it triggers:** After a user approves/accepts a workflow step and the step status changes to "Accepted". **Required Fields:** - **Type**: `onWorkflowStepAccepted` - **Checked Field**: Step number (e.g., "1", "2", "3") - **Checked Value**: "Accepted" - **Workflow ID**: The workflow this listener applies to - **Custom Code**: JavaScript code to execute when triggered **Use Cases:** - Send notification when critical step is approved - Auto-populate fields after approval - Create comments or logs for audit trail **Example:** ``` Type: onWorkflowStepAccepted Checked Field: 3 Checked Value: Accepted Workflow ID: 5 Custom Code: await sendMailTo(["manager@example.com"], "Step 3 approved", "Workflow Progress") ``` #### 2. onValueChanged **Description:** Triggers when a specific punch detail field value changes to a specified value. **When it triggers:** After a ticket field is updated and the new value matches the specified CheckedValue. **Required Fields:** - **Type**: `onValueChanged` - **Checked Field**: Field name (e.g., "Status", "Priority") - **Checked Value**: The value that triggers the listener (e.g., "Closed", "High") - **Workflow ID** (or **Default**: true): Either specify a workflow or make it workflow-independent - **Custom Code**: JavaScript code to execute when triggered **Use Cases:** - Notify team when status changes to "Closed" - Auto-populate related fields when priority is set - Trigger external API when specific conditions are met **Example:** ``` Type: onValueChanged Checked Field: Status Checked Value: Closed Default: false Workflow ID: 5 Custom Code: await setTicketValue("ClosedDate", Date()) ``` #### 3. onTicketCreated **Description:** Triggers when a new ticket is created. **When it triggers:** Immediately after a new ticket is created in the system. **Required Fields:** - **Type**: `onTicketCreated` - **Default**: Typically set to `true` (apply to all new tickets) - **Custom Code**: JavaScript code to execute when triggered (can include filtering logic) **Use Cases:** - Auto-assign new tickets based on criteria - Set initial field values - Send creation notifications - Apply default workflows **Example:** ``` Type: onTicketCreated Default: true Custom Code: const area = await getTicketValue("Area"); if (area === "Engine Room") { await setTicketValue("AssignedTo", "engineering@example.com"); } ``` #### 4. onInteractionEmailSent **Description:** Triggers when an interaction email is sent from the support ticket system, filtered by regex patterns matching the email subject and/or body content. **When it triggers:** After an email is sent successfully through the Interactions tab of a ticket, if the email subject matches the Subject Regex **and** the email body matches the Content Regex. **Required Fields:** - **Type**: `onInteractionEmailSent` - **Subject Regex**: Regular expression pattern to match email subject (max 500 characters) - **Content Regex**: Regular expression pattern to match email body (max 500 characters) - **Workflow ID** (or **Default**: true): Either specify a workflow or make it workflow-independent - **Custom Code**: JavaScript code to execute when triggered **Important Notes:** - The listener runs for **every** sent email that matches, not only once per ticket - An empty Subject Regex or Content Regex matches every email. An invalid pattern is compared as plain text - Regex patterns are case-sensitive unless specified otherwise in the pattern - The custom code runs as the user who sent the email. `getEmailData()` returns `{ from, subject, body }` of the sent email; `getRegexMatches()` returns the capture groups of the regex matches - If the custom code fails, the email is still sent; the error is written to the server log **Use Cases:** - Track specific keywords in outgoing emails - Log emails containing certain phrases - Trigger actions based on email content (e.g., escalate tickets with "urgent" in subject) - Create audit trail for compliance **Regex Examples:** **Match emails with "Invoice" in subject:** ``` Subject Regex: Invoice Content Regex: (leave empty or .*) ``` **Match emails containing specific order numbers in body:** ``` Subject Regex: .* Content Regex: ORDER-\d{6} ``` **Match urgent emails:** ``` Subject Regex: (?i)(urgent|critical|emergency) Content Regex: .* ``` **Configuration Example:** ``` Type: onInteractionEmailSent Subject Regex: (?i)urgent Content Regex: .* Custom Code: await setTicketValue("Priority", "High"); await sendMailTo(["manager@example.com"], "Urgent email detected", "Priority Escalation"); ``` #### 5. onTicketOverdue **Description:** Triggers on a scheduled basis for open tickets whose monitored date field is older than a specified overdue threshold. **When it triggers:** A background job checks all `onTicketOverdue` listeners at a fixed server interval (default: every 5 minutes, server setting `Worker:ListenerIntervalMinutes`). A ticket triggers the listener when its status is "Open" and the date in the **Checked Field** is older than the **Overdue** threshold. **Required Fields:** - **Type**: `onTicketOverdue` - **Checked Field**: The date field to monitor (e.g., "Due Date") - **Overdue**: Time threshold in milliseconds (e.g., 86400000 = 24 hours) - **Custom Code**: JavaScript code to execute for each overdue ticket - **Disabled**: Must be `false` for the listener to run **Important Notes:** - The **Interval** field is stored but **not used**. All overdue listeners are checked at the server interval above. - Setting **Disabled** to `true` excludes the listener from the check - Executes once for each ticket that meets the overdue criteria (see [once per ticket](#understanding-listener-types)) - Store dates in a consistent, unambiguous format (e.g., `yyyy-MM-dd`) **Common Overdue Values:** - 3600000 - 1 hour - 86400000 - 24 hours (1 day) - 604800000 - 7 days (1 week) **Use Cases:** - Send reminder notifications for overdue tickets - Escalate tickets that haven't been updated - Auto-update priority for old tickets - Generate overdue reports **Configuration Example:** ``` Type: onTicketOverdue Checked Field: Due Date Overdue: 172800000 (48 hours) Disabled: false Custom Code: await sendMailTo( [await getTicketValue("AssignedTo")], "Ticket #" + UniqueID + " is overdue!", "Overdue Ticket Reminder" ); ``` ## Special Configuration Fields ### Default Flag **Type:** Boolean (checkbox) **Default Value:** false **Purpose:** The **Default** flag transforms workflow-dependent listeners into workflow-independent (global) listeners. **How it works:** - **Default = false**: Listener only triggers for tickets assigned to the specified Workflow ID - **Default = true**: Listener triggers for **ALL** tickets regardless of workflow assignment, making it globally applicable **When to use Default = true:** - Organization-wide automation that applies to all tickets - Global monitoring and notifications - Universal field updates based on conditions - System-wide audit logging **Examples:** **Workflow-Specific Listener (Default = false):** ``` Type: onValueChanged Checked Field: Status Checked Value: Closed Default: false Workflow ID: 5 Custom Code: await sendMailTo(["team@example.com"], "Project X ticket closed", "Notification") ``` → Only triggers for tickets with Workflow ID = 5 **Global Listener (Default = true):** ``` Type: onValueChanged Checked Field: Status Checked Value: Closed Default: true Workflow ID: (can be null) Custom Code: await setTicketValue("ClosedDate", Date()) ``` → Triggers for **all tickets** when Status changes to "Closed", regardless of workflow ### Disabled Flag **Type:** Boolean (checkbox) **Default Value:** false **Purpose:** The **Disabled** flag completely stops listener execution without deleting the configuration. **How it works:** - **Disabled = false**: Listener is active and will trigger when conditions are met - **Disabled = true**: Listener is completely inactive and will **never** trigger, even if conditions are met **Special behavior for onTicketOverdue:** - Setting **Disabled = true** excludes the listener from the scheduled overdue check - Setting **Disabled = false** includes it again at the next check **When to use Disabled = true:** - Temporarily pause automation during maintenance - Disable problematic listeners while debugging - Seasonal or conditional listeners (enable/disable as needed) - Testing alternative implementations **Best Practice:** Use Disabled instead of deleting listeners to preserve configuration for future use. ## Listeners Table  The Listeners Table: - Displays all configured event listeners in a tabular format - Shows Type, Checked Field, Checked Value, Workflow, Default, Disabled, and other type-specific columns - Provides an interface to add, edit, and delete listeners - Integrates with punch workflows and punch details ## Managing Event Listeners ### Add a Listener 1. Click the **Add Row (+)** button above the table 2. **Select the Type** from the dropdown (required first step) 3. Enter the **type-specific required fields:** - For **onWorkflowStepAccepted**: Checked Field (step number), Checked Value ("Accepted"), Workflow ID - For **onValueChanged**: Checked Field (field name), Checked Value (trigger value), Workflow ID or Default - For **onTicketCreated**: Default (typically true) - For **onInteractionEmailSent**: Subject Regex and/or Content Regex - For **onTicketOverdue**: Checked Field (date field), Overdue (milliseconds) 4. **Configure special flags:** - **Default**: Check to make listener workflow-independent (applies globally) - **Disabled**: Check to temporarily disable the listener 5. **Write Custom Code:** - Click the Custom Code cell to open the code editor - Write JavaScript using available [Custom Code](#custom-code) functions - Test and save the code 6. Press **Enter** or click the **Save icon** at the end of the row to save the new listener ### Edit a Listener 1. Click the **Edit (pencil) icon** on the listener row 2. Modify any fields: - Change Type (note: required fields will change) - Update Checked Field/Value - Modify regex patterns for email listeners - Adjust Checked Field/Overdue for overdue listeners - Toggle Default or Disabled flags - Update Custom Code 3. Click **Save** to apply changes ### Delete a Listener 1. Click the **Trash icon** on the listener row 2. Confirm deletion when prompted **Note:** A deleted onTicketOverdue listener is no longer included in the scheduled overdue check. ### Test a Listener **Before Activating:** 1. Configure the listener with Disabled = true 2. Test the custom code using the Custom Code editor 3. Verify the trigger conditions are correct 4. Set Disabled = false to activate **Live Testing:** 1. Create or modify a ticket to match the trigger conditions 2. Verify the listener executes (check logs, email notifications, field updates) 3. Review any errors in the system logs ## Custom Code Integration Event listeners utilize the full [Custom Code](#custom-code) API. When a listener triggers, the custom code executes with access to: - All ticket fields via `getTicketValue()` and `setTicketValue()` - Workflow control functions like `stepForwardJumpTo()` - Communication functions like `sendMailTo()` - File operations like `createPdfReport()` - Utility functions like `Date()` **Workflow jumps in listeners:** `stepForwardJumpTo()` and `stepBackwardJumpTo()` move the ticket's pending workflow step: - A listener with a **Workflow ID** moves the pending step of that workflow. - A **Default** listener moves the pending step only when the ticket has exactly one pending step. Otherwise nothing moves. - A jump to the pending step's own number keeps the step pending. If the custom code fails, nothing moves. - `onTicketOverdue` and `onEmailReceived` listeners cannot jump: the request is only written to the server log. **Important:** Event listeners execute **after** the triggering event has already occurred and been saved to the database. They cannot prevent or block the event (unlike [Field Validators](#field-validators)). ## Comparison: Event Listeners vs Field Validators | Feature | Event Listeners | Field Validators | | ----------------------- | ------------------------------------------- | -------------------------------- | | **Trigger Timing** | After event occurs (post-save) | Before save (immediate) | | **Blocking** | Non-blocking (cannot prevent events) | Blocks invalid changes | | **Purpose** | React to changes, automate actions | Prevent invalid data entry | | **User Feedback** | Background execution, no immediate feedback | Immediate error message in toast | | **Multi-field Support** | Single field per listener | Multiple fields per validator | | **Execution Context** | Full Custom Code API | Validation-specific helpers | **When to use Event Listeners:** - Send notifications when conditions are met - Auto-populate fields after changes - Trigger external integrations - Log events for audit trail - Schedule periodic checks **When to use Field Validators:** - Enforce data format requirements - Validate business rules before saving - Prevent invalid field values - Cross-field validation - Role-based field restrictions See [Field Validators](#field-validators) for detailed validation documentation. ## Best Practices ### Listener Design - Use descriptive naming in Custom Code comments - Test listeners thoroughly before deploying to production - Use Default = true sparingly (only for truly global automation) - Keep custom code focused and maintainable ### Performance - Avoid heavy processing in frequently-triggered listeners - For onTicketOverdue, choose an Overdue threshold that matches the business need; the check runs at a fixed server interval - Consider using Disabled flag during high-load periods ### Error Handling - Include error handling in custom code (try/catch blocks) - Test edge cases (null values, missing fields, etc.) - Monitor system logs for listener execution errors ### Regex for Email Listeners - Test regex patterns before deploying - Use case-insensitive matching when appropriate: `(?i)pattern` - Escape special regex characters: `\.`, `\?`, `\+`, etc. - Keep patterns under 500 characters ### Workflow Integration - Document which workflows have listeners attached - Coordinate with workflow designers to avoid conflicts - Use Default flag consistently across related listeners # Custom Code The **Custom Code** feature enables administrators to write JavaScript code that executes custom logic and automation throughout the Toolkit application. This powerful feature is used in multiple components: 1. **Workflow Steps** - Execute actions when workflow steps are accepted or disapproved 2. **Email Message Templates** - Generate dynamic email content with ticket data 3. **Punchfield Mapping** - Transform attribute values during ticket creation 4. **Event Listeners** - Automate actions triggered by specific events (see [Event Listeners](#event-listeners)) 5. **Field Validators** - Enforce custom validation rules on ticket fields (see [Field Validators](#field-validators)) ## Security & Execution Environment Custom code is run as JavaScript in a **secured sandbox environment** with the following protections: - **Sandboxed Execution**: Restricts access to internal system functions and prevents malware execution - **Code Length Limit**: Maximum 50,000 characters per code block. Enforced when the code is saved (workflow steps, event listeners, email message templates and field validators) and when it is tested with the Compile button - **Dangerous Pattern Detection** (field validators only): When a field validator is saved, code containing SQL statements, `eval()`, `require()`, process access, prototype access and other risky patterns is rejected. Workflow step code and event listener code are not checked for these patterns. - **Server-Side Execution**: All custom code runs on the server, never exposing sensitive operations to the client ## Available Objects Custom code has access to the following predefined objects: - **`ActionResult`**: Enum containing workflow action results ```javascript ActionResult = { Yes: "Yes", No: "No", Undefined: "Undefined", }; ``` - **`userAction.Result`**: Contains the result of the current workflow step action (ActionResult value) - **`language`**: String containing the current user's language code (e.g., "en-US", "ko") **Usage example:** ```javascript if (userAction.Result === ActionResult.Yes) { console.log("The step was approved"); await setStatus("Approved"); } else { console.log("The step was disapproved"); await setStatus("Rejected"); } ``` ## Available Functions ### Ticket Management Functions - **`getPunchlistDetails()`** Returns an **array** with one row per ticket field value: `{ PunchlistDetails: { Detail }, Value, PunchDetailID }`. It does not return a name→value object. For a single field, use `getTicketValue()`. ```javascript const rows = await getPunchlistDetails(); const stage = rows.find((r) => r.PunchlistDetails.Detail === "Stage")?.Value; console.log(stage); // "In Review" ``` - **`updatePunchlistDetails(data: Map
In order to set your own index.html file that for example contains your corporate identity or an automatic redirect to a specific instance do the following.
Put your custom index.html file in the same folder as the docker-compose.yml file. Than uncomment the volume mapping in the docker-compose.yml file:
before -> leads to generation of default landing page
```
# volumes:
# - ./index.html:/usr/share/nginx/html/index.html:ro
```
after -> your specified index.html file is used instead of the auto-generated one:
```
volumes:
- ./index.html:/usr/share/nginx/html/index.html:ro
```
Here is an example how this can look like:
---
# Toolkit App for UDiTH — Custom Code and Macro Reference
# Custom Code and Macro Reference
This document provides a complete reference for the ExecutorCustomCode macro system, including workflow step macros, event listeners, and field validators. It covers all available capabilities, how to use them, and their current implementation status.
> **Related Administration Pages:**
>
> - [Workflows](#1-workflow-step-macros) — Settings > Workflows
> - [Event Listeners](#2-workflow-level-event-macros) — Settings > Listeners
> - [Field Validators](#field-validators-valuechangevalidating) — Settings > Workflows > Validators
> - [Custom Code Editor](#custom-code-editor) — Embedded in Workflows, Listeners, and Validators pages
---
# 1. Macro Requirements
## A. One Macro per Workflow Step
Each workflow step can have a **Custom Code** block that executes when the step is accepted or denied.
**How to configure:**
1. Navigate to **Settings > Workflows**
2. Select a workflow from the list
3. Click the **Code** cell for the desired workflow step
4. Write JavaScript code in the integrated code editor
5. Click **Compile** to verify syntax, then **Save**
**How it works:**
- The macro runs when the workflow step is triggered (accepted or denied)
- The `userAction.Result` object tells you whether the step was accepted (`ActionResult.Yes`) or denied (`ActionResult.No`)
- Each step can have exactly one code block
**Example:**
```javascript
if (userAction.Result === ActionResult.Yes) {
await setStatus("Approved");
await sendMailTo(
["manager@example.com"],
"Step approved for Ticket #" + UniqueID,
"Workflow Progress"
);
} else {
await stepBackwardJumpTo(1, "Returned to initial review");
}
```
> **Note:** In addition to workflow step macros, you can use [Event Listeners](#2-workflow-level-event-macros) for event-driven automation that is not tied to a specific step action.
---
## B. Workflow-Level Event Macros
Event listeners enable macros that trigger on specific events across the application. Unlike step macros, event listeners react to conditions such as field changes, email receipts, and scheduled intervals.
**How to configure:**
1. Navigate to **Settings > Listeners**
2. Click the **Add (+)** button
3. Select a **Type** from the dropdown
4. Configure the required fields for that type
5. Write Custom Code and save
### Available Event Types
| Event Type | Trigger | Required Fields |
|---|---|---|
| `onWorkflowStepAccepted` | A workflow step is accepted | Checked Field (step number), Checked Value, Workflow ID |
| `onValueChanged` | A ticket field value matches a condition | Checked Field (field name), Checked Value |
| `onTicketCreated` | A new ticket is created | Default (typically `true`) |
| `onInteractionEmailSent` | An interaction email is sent | Subject Regex, Content Regex |
| `onTicketOverdue` | Scheduled check for overdue tickets | Checked Field (date field), Overdue (ms) |
| `onEmailReceived` | An inbound email is received | Subject Regex, Content Regex |
> **Note:** The **Interval** field is stored but not used. Scheduled checks run at fixed server
> intervals: overdue tickets every 5 minutes (`Worker:ListenerIntervalMinutes`), inbound email
> every minute (`Worker:EmailIngestionIntervalMinutes`).
> **Important — a listener runs only once per ticket.** After a listener has run for a ticket,
> it does not run for that ticket again, even if its condition becomes true again later (for
> example, the same step is accepted a second time). The run is recorded even if the custom code
> fails. `onEmailReceived` and `onInteractionEmailSent` listeners are the exception: they run for
> every matching email.
### ValueChangeValidating
Field validators provide a pre-save validation event. When a ticket field value changes, all active validators for that field run **before** the value is saved.
**How to configure:**
1. Navigate to **Settings > Workflows > Validators**
2. Select a workflow from the dropdown
3. Click **Add** to create a new validator
4. Select one or more fields from the **Fields** TagBox
5. Enter an **Error Message** (shown to the user on failure)
6. Write validation code that returns `true` (allow) or `false` (block)
See [Field Validators](#field-validators-valuechangevalidating) for full details.
### ValueChanged (onValueChanged)
Triggers **after** a ticket field value changes to a specified value. Unlike validators, listeners cannot block the change.
**Configuration example:**
```
Type: onValueChanged
Checked Field: Severity
Checked Value: Critical
Custom Code:
await stepForwardJumpTo(5, "Critical severity detected - escalating");
```
### EmailReceived
Triggers when an inbound email matches regex patterns on subject and/or body content.
**Configuration example:**
```
Type: onEmailReceived
Subject Regex: (Out of Office|Automatic reply)
Content Regex: .*
Custom Code:
console.log("Auto-reply detected");
```
---
# 2. Required Capabilities
## A. Detecting Received Emails
The system can detect inbound emails with specific content using regex pattern matching.
**How to configure:**
1. Navigate to **Settings > Listeners**
2. Add a listener with **Type** = `onEmailReceived`
3. Set **Subject Regex** (regex pattern to match the email subject)
4. Set **Content Regex** (regex pattern to match the email body)
5. Write Custom Code to execute when a matching email is found
**Use cases:**
- Detect autoresponder / out-of-office replies: `Subject Regex: (?i)(Out of Office|Automatic reply|Abwesenheit)`
- Detect approval keywords in email body: `Content Regex: (?i)(approved|confirmed)`
- Set ticket fields from values in the email (via `getRegexMatches()`)
**How it works internally:**
- A background job reads new emails from the support mailbox every minute (server setting
`Worker:EmailIngestionIntervalMinutes`). The listener's **Interval** field is not used.
- Each email is linked to a ticket: the ticket named by `[#123]` at the end of the subject, else the
ticket of the same email conversation, else a new ticket. The listener code runs for that ticket.
- An email that was already imported (same mail ID) is skipped, so it is never processed twice.
- Every enabled `onEmailReceived` listener is checked, independent of the ticket's workflow.
- An empty Subject Regex or Content Regex matches everything. An invalid pattern is compared as
plain text.
- When matched, the listener's Custom Code executes with full access to the macro API. It runs
without a user, so `createComment` does nothing (a server warning is logged).
**Email-specific helpers** (only in `onEmailReceived` and `onInteractionEmailSent` listeners):
| Function | Returns |
|---|---|
| `getEmailData()` | `{ from, subject, body }` of the received or sent email (`body` is the HTML body; for a sent email, `from` is the support mailbox). `null` in all other listener types |
| `getRegexMatches()` | Array of the capture groups from the Subject Regex match, then from the Content Regex match. `[]` in all other listener types |
```javascript
// Subject Regex: Order (\d+)
const e = getEmailData();
const m = getRegexMatches();
await setTicketValue("Order No", m[0]);
await sendMailTo(["orders@example.com"], "Mail from " + e.from, "Order " + m[0] + " received");
```
---
## B. Detecting Ticket Value Changes
Two systems detect ticket value changes:
### System 1: Event Listeners (post-change)
Listeners of type `onValueChanged` check if a field has a specific value after a change.
**Configuration:**
| Field | Value |
|---|---|
| Type | `onValueChanged` |
| Checked Field | Field name (e.g., `Severity`) |
| Checked Value | Target value (e.g., `Critical`) |
| Workflow ID | Target workflow (or set Default = true for all) |
**Example: Route to different workflow based on severity**
```javascript
// Listener: onValueChanged, CheckedField: "Severity", CheckedValue: "Critical"
await stepForwardJumpTo(5, "Escalated due to critical severity");
await sendMailTo(
["escalation-team@example.com"],
"Ticket has been escalated to critical severity.",
"Critical Escalation"
);
```
### System 2: Field Validators (pre-change)
Validators run **before** the value is saved and can **block** the change.
**Example: Different validation based on severity**
```javascript
// Validator on "Severity" field
// ErrorMessage: "Only managers can set severity to Critical"
if (getCurrentFieldValue() === "Critical") {
return hasRole("Manager");
}
return true;
```
---
## C. User Rights
Custom code can access the current user's roles to enforce permission-based logic.
### In Field Validators
The `hasRole(roleName)` function is available and checks whether the current user has a specific role.
**Example:**
```javascript
// Only users with "Editor" role can modify this field
if (!hasRole("Editor")) {
return false; // ErrorMessage: "You don't have the right to modify this value."
}
return true;
```
**Available helper:**
| Function | Description |
|---|---|
| `hasRole(roleName)` | Returns `true` if the current user has the named role, `false` otherwise |
**Available variable:**
| Variable | Description |
|---|---|
| `userRoles` | Array of the current user's role names (e.g., `["Admin", "Editor"]`) |
### In Workflow Step Macros and Event Listeners
User roles are **not** directly available in workflow macros. The executor receives `userID` but roles are not pre-loaded into the execution context.
---
# 3. Actions Within a Macro
## Trigger a Jump to a Certain Workflow Step
Custom code can override the default forward/backward step configured in the workflow table.
### stepForwardJumpTo(stepNumber, message?)
Jumps to the specified step number as a **success/approval** action. Overrides the Forward Step ID column.
```javascript
// Skip to step 5 with an activity log message
await stepForwardJumpTo(5, "Auto-approved based on priority");
```
### stepBackwardJumpTo(stepNumber, message?)
Jumps to the specified step number as a **failure/denial** action. Overrides the Backward Step ID column.
```javascript
// Send back to step 1 for rework
await stepBackwardJumpTo(1, "Additional information required");
```
> **Note:** When these functions are used, they take **priority over the Forward Step ID and Backward Step ID values** defined in the workflow table.
> **Note:** The message is posted to the activity chat under the acting user once the jump has
> advanced. A script running without a user (an auto-executed `None` step triggered by attaching
> the workflow, or by the Worker) has no author for the comment — the message is written to the
> server log instead.
> **Note — jumps in event listeners:** A listener has no step of its own, so the jump moves the
> ticket's **pending** step. A listener with a Workflow ID moves the pending step of that workflow.
> A Default listener moves the pending step only when the ticket has exactly one pending step;
> otherwise nothing moves. A failed script does not jump. `onTicketOverdue` and `onEmailReceived`
> listeners cannot jump — the request is only written to the server log.
### Staying on the Current Step
A jump to the step's **own** step number means "stay here". The step is not accepted or denied,
no new step is created, and the step stays pending. Use this when a precondition is not met yet.
```javascript
// Step 1: do not move on until the CTR discipline is filled in
const ctr = await getTicketValue("CTR Discipline First Action Owner");
if (!ctr) {
await showPopup("Please fill in 'CTR Discipline First Action Owner' before approving.");
await stepBackwardJumpTo(1); // this code runs on step 1 -> stay on step 1
return false;
}
await stepForwardJumpTo(2);
return true;
```
> **Note:** The user sees no "Step approved" message when the step stays. Tell them what to do
> with [`showPopup`](#showpopupmessage) — otherwise the click appears to do nothing. On a `None`
> step a self-jump simply stops the automatic execution; the step waits.
---
## Refuse to Modify a Value
Field validators can prevent a value from being saved by returning `false`.
**How it works:**
1. User changes a field value
2. All active validators for that field execute in order
3. If any validator returns `false`, the change is **blocked**
4. The configured **Error Message** is shown as a toast notification
5. The field retains its previous value
**Example: Prevent unauthorized changes**
```javascript
// Validator on "Budget" field
// ErrorMessage: "You don't have the right to modify this value."
if (!hasRole("Finance")) {
return false;
}
return true;
```
**Example: Conditional refusal**
```javascript
// Validator on "Status" field
// ErrorMessage: "Cannot close ticket without a resolution."
if (getCurrentFieldValue() === "Closed") {
const resolution = getFieldValue("Resolution");
return resolution && resolution.trim() !== "";
}
return true;
```
---
# 4. Misc Functions
## A. Show Message
### In Field Validators
When a validator returns `false`, the **Error Message** configured on the validator is displayed to the user as a toast notification. This is the primary mechanism for showing messages during field validation.
**How to configure:**
1. Navigate to **Settings > Workflows > Validators**
2. Create or edit a validator
3. Set the **Error Message** field (max 500 characters)
4. Write validation code that returns `false` when the message should be shown
**Example:**
```
Error Message: "You don't have the right to modify this value."
Custom Code: return hasRole("Editor");
```
### In Workflow Step Macros
#### showPopup(message)
Shows a popup with `message` to the user whose action ran the code. The popup opens after the
step has been processed — on the Approvals tab and on the Kanban board. For an automatic `None`
step the user is the one who attached the workflow, or who accepted/denied the step before it.
```javascript
// Tell the approver what happened next
await showPopup("The ticket was forwarded to the modelling discipline.");
return true;
```
**Example: Explain why the step did not move on**
```javascript
const description = await getTicketValue("Tag Description");
if (!description) {
await showPopup("Add a Tag Description first. The step stays open.");
await stepBackwardJumpTo(3); // this code runs on step 3 -> stay on step 3
return false;
}
return true;
```
**Example: Several lines**
```javascript
// Each call adds a line to the same popup
await showPopup("Checks passed:");
await showPopup("- Tag Description present");
await showPopup("- CTR discipline: " + (await getTicketValue("CTR Discipline First Action Owner")));
return true;
```
**Behaviour:**
- Several calls are shown in **one** popup, one line each, in call order.
- The text is shown as plain text. HTML tags in the message are not rendered.
- Messages from a chain of automatic `None` steps are shown together with the message of the
step the user clicked, in execution order.
- The popup needs a user in a browser. An event listener, or a `None` step run by the server
without a user, has none: the message is written to the server log and not shown.
- **Compile** prints `showPopup: Ticket #${UniqueID} has been approved.
Ticket #${UniqueID} has been approved.
`, "Ticket Approval Notification" ); ``` | Function | Parameters | Description | |---|---|---| | `Date(format?)` | `format`: date-fns format string (default: `yyyy-MM-dd`) | Current date. Works as `${Date}` or `Date("format")` | | `FormatDate(dateInput, format?)` | `dateInput`: Date, string, or timestamp; `format`: output format (default: `yyyy-MM-dd`) | Format any date value. Returns `""` on invalid input | | `ParseFormatDate(str, inFmt, outFmt?)` | `str`: date string; `inFmt`: input format; `outFmt`: output format (default: `yyyy-MM-dd`) | Parse a date string with known format and reformat it | ### Usage in Email Templates Template variables are used in Workflow Email Messages (configured in the workflow table) and in `sendMailTo()` message/subject parameters: ```htmlTicket #${PunchItem} has been updated.