# Linking

Model links are the recommended way to create shareable links and deep links to a model in UDiTH. UDiTH Portal generates and manages these URLs for you: it resolves the model alias, selects the requested version, applies the Portal authentication, and checks the permissions of the user before the model is opened.

A model link is a normal HTTPS URL. You can use it in documents, websites, e-mails, and reports, and it stays valid when a new model version is published.

> ℹ️ **When to use this page**
>
> - **With UDiTH Portal:** use a model link, as described below. This is the recommended method.
> - **Without UDiTH Portal:** build the deep link manually with the `upvapi://` URL handler. See [Linking and API](/UDiTH%20App/Linking%20and%20API).

## URL format

```
https://<portal-url>/modellink/<alias-or-identifier>
https://<portal-url>/modellink/<alias-or-identifier>/<version>
```

The `<alias-or-identifier>` is the external identifier of a model in the [Central Model Repository](/UDiTH%20Portal/Central%20Model%20Repository), or one of its aliases.

If no version is specified, the `latest` version is used.

## Query Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `openLocal` | `true` | When `true`, returns a `upvapi://` link that opens the model in the local UDiTH viewer. When `false`, returns an `https://` link that opens the model in the browser (BBV). |
| `commands` | — | Optional commands to pass to the viewer. Multiple commands are separated by `&`. See below. |

## Commands

The `commands` parameter accepts all UDiTH deeplink commands. Commands are concatenated with `&` and must be URL-encoded in the query string.

A query condition uses the syntax `<key>=<value>` and filters or selects objects by the given attribute key and value. A command uses the syntax `CMD!<Command>`, with an optional value after `=`.

**Example (decoded):**
```
Name=D-240&CMD!Select&CMD!Fit&CMD!Highlight
```
This filters by attribute `Name` with value `D-240`, then applies selection, fits the camera to it, and highlights it.

**Example (encoded):**
```
commands=Name%3DD-240%26CMD%21Select%26CMD%21Fit%26CMD%21Highlight
```
This is the same example after URL encoding, as it must be written in the query string. `=` becomes `%3D`, `&` becomes `%26`, and `!` becomes `%21`.

### Wildcards

Use `_` for any single character and `*` for any number of characters.

### Condition Operators

By default, query conditions are combined using **AND**:

```
Name=K-001&NozzleName=N5
```

However, you can use **OR** with the combine command:

```
Name=K-001&Name=D-100&CMD!Combine=OR
```

### Selection, visibility and appearance

| Command | Description |
|---------|-------------|
| `Select` | Selects the specified object.<br>**Example:** `Name=D-100&CMD!Select` |
| `ShowOnly` | Sets all query objects to visible and hides all other objects. |
| `Highlight` | Highlights the specified object.<br>**Example:** `Name=D-100&CMD!Highlight` |
| `ClearHighlight` | Disables highlighting. |
| `ClearSelection` | Clears the current selection. |
| `Combine` | `Combine=[OR/AND]` uses `OR` between query conditions instead of `AND`, which is the default. |
| `SearchFallback` | Automatically adds the search string to the search box. If the exact search returns no results, a fuzzy search is started automatically. |
| `SetVisibility` | `SetVisibility=[True/False]` |
| `SetVisibleAspects` | `SetVisibleAspects=[aspect!aspect]`<br>**Example:** `CMD!SetVisibleAspects=Simple Physical!Insulation` shows both insulation and simple physical. |
| `Color` | `Color=[HTML colour code]` using the format `#RRGGBB` or `#RRGGBBAA`.<br>**Example:** `CMD!Color=#FF0000` |
| `ClearColor` | Restores the original object colours. |
| `ClearCustomAttributes` | Resets all changes made to custom attributes during the current session. |
| `SetTreeConfiguration` | `SetTreeConfiguration=[discipline!discipline...]`<br>**Example:** `CMD!SetTreeConfiguration=Task!SystemPath` |

### Camera, clipping and screenshots

| Command | Description |
|---------|-------------|
| `Fit` | Fits the camera to the current selection. Optional parameter: `Centred`.<br>`true` (default): fits to the centre of the box.<br>`false`: fits to the screen borders of the current view.<br>**Example:** `CMD!Fit=true` |
| `ResetView` | Resets the camera mode, camera position, rotation, and states such as highlighting to the state used when the model was loaded. |
| `SetCameraView` | `SetCameraView=[X!Y!Z!rotationX!rotationY!rotationZ]` using Euler angles.<br>**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]`<br>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.<br>**Example:** `CMD!SetClippingPlane=20!30` |
| `IntelliClip` | `IntelliClip=[distance in metres]`<br>Values `> 0` display only the object. `0` also displays objects touching the selected object. Decimal values are supported. |
| `VolumeClip` | `VolumeClip=[distance in metres]`<br>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, in this order: X min, Y min, Z min, X max, Y max, Z max.<br>**Example:** `CMD!VolumeClipByCoordinates=-10.0!-10.0!-10.0!20.0!20.0!20.0` |
| `ClearClipping` | Disables clipping. |
| `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`).<br>**Example:** `CMD!TakeAndSaveScreenshot=C:\Test\image.jpg!2000!1500!120!png!true!true!true!false` |

### Files, messages and application

| Command | Description |
|---------|-------------|
| `LoadColorFile` | `LoadColorFile=[online or offline location]`<br>Local: `CMD!LoadColorFile=C:\colors.xlsx`<br>Via HTTP: `CMD!LoadColorFile=http://example.com/colors.xlsx`<br>Via UNC: `CMD!LoadColorFile=file://////server/share/colors.xlsx`<br>Note: for UNC paths, it is important to use six slashes (`//////`) after `file`. |
| `LoadConfigFile` | Loads a configuration file. Parameters: configuration file name, and combine mode (optional).<br>By default, existing settings are cleared. `Merge` keeps existing views and merges them, overriding existing values with those from the configuration file.<br>**Example:** `CMD!LoadConfigFile=C:/config.upv!Merge` |
| `LoadLinkFile` | `LoadLinkFile=[online or offline location]`<br>Local: `CMD!LoadLinkFile=C:\links.xlsx`<br>Via HTTP: `CMD!LoadLinkFile=http://example.com/links.xlsx`<br>Via UNC: `CMD!LoadLinkFile=file://////server/share/links.xlsx`<br>Note: for UNC paths, it is important to use six slashes (`//////`) after `file`. |
| `ClearLinks` | Removes links loaded from link files. |
| `LoadPackageFile` | Loads package files from the specified path. Parameters: URL, and `Replace` (optional). If `Replace` is set to `true`, current packages are replaced instead of being added to the existing ones.<br>**Example:** `CMD!LoadPackageFile=c:\package.upvf!true` |
| `ExportPackageFile` | Exports package files to the specified path. |
| `LoadSketch` | Loads a sketch from the specified path. A second parameter can be used to rename the sketch.<br>**Example:** `CMD!LoadSketch=C:\Sketch\SketchFile.upvsk!NewName` |
| `ShowMessage` | Shows a message and title in a message box.<br>**Example:** `CMD!ShowMessage=Your Message!Your Title` |
| `FocusViewer` | Brings the UDiTH window to the foreground and gives it the input focus. This command only has an effect on a local model. |
| `SetStorageVariable` | Sets a storage variable. Parameters, in this order: the key to set, the value, and an optional persist flag (`true` or `false`, default `false`). Use this command with the LocalStorage Universal API system to send a message to a running AppControl.<br>**Example:** `CMD!SetStorageVariable=MyKey!MyValue` |

## Examples

| URL | Behaviour |
|-----|-----------|
| `/modellink/myplant` | Opens the latest version of model `myplant` in local viewer |
| `/modellink/myplant/2025_10_23` | Opens version `2025_10_23` in local viewer |
| `/modellink/myplant?openLocal=false` | Opens latest version in browser (BBV) |
| `/modellink/demoplant?openLocal=false&commands=Name%3DD-240%26CMD%21Select%26CMD%21Fit%26CMD%21Highlight` | Opens model `demoplant` in browser, selects object `D-240`, fits and highlights it |

> ℹ️ The user must be authenticated to use model links. Unauthenticated users are redirected to the login page first.