Show only results for:











Linking and API

To link from an object to an external source, use a link file.

In order to link from an external source to an object in UniversalPlantViewer use deep linking.

Deep linking API: Link from outside > UniversalPlantViewer > Link to outside

UniversalPlantViewer uses link files to store link information. Link files are loaded automatically when you open UniversalPlantViewer but you can also load them manually at any time via File management > Load a link file ().

Link files are created using Excel. The Excel file needs the following rows:

Condition Link Name
Task=Piping https://www.caxperts.com/ Homepage
Task=Structure https://en.wikipedia.org/wiki/Structure Wikipedia

Condition can be any attribute. * can be used as a wildcard to select every object, e.g.:

Task=*

Link can be a URL or local path. For condition you can use all attributes You can use absolute and relative paths (with backslash “\”).

data\docs\Valve.pdf

Name is the text shown in UPV for the link.

UniversalPlantViewer automatically links objects in 3D models with their symbols in isometric and P&ID drawings. Therefore you can open drawings from the 2D / P&ID level of your project tree and also from the link list.

It is possible to select an object in the 3D model by clicking on a symbol in a drawing that is highlighted when you hover your mouse pointer over it:

Because drawings are rendered in PDF format you can zoom in without loss of quality.

You can generate a double-sided ISO PDF and preview the 3D objects to be included.

Links to objects in the 3D model will be lost.

Deep linking

You can include deep links in all types of documents that support links, i.e. Word, websites, email … to open UniversalPlantViewer and transfer a combination of queries and commands.

Deep linking uses the URL handler upvapi://

Structure:

upvapi://<MODEL-URL>?<QUERY>&<COMMANDS>

Example:

upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=K-001&NozzleName=N3&CMD!Select&CMD!Fit&CMD!Highlight

Wildcards:

Use _ (any character) and * (any number of characters) as wildcards.

Example:

upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=K-001&NozzleName=N3&CMD!Select&CMD!Fit&CMD!Highlight

This will look for the Nozzle 3 on the object K-001, select and fit it to the screen while greying out all other objects.

UPVSelected

By adding UPVSelected=true or UPVSelected=false you can limit your query to items that are currently selected / not selected in UniversalPlantViewer.

Example:

upvapi://http://demo.universalplantviewer.com/demoPlant/5/0?Name=D-100&UPVSelected=true&CMD!Select&CMD!Fit&CMD!FocusViewer&CMD!Combine=Or

This example using Combine=Or adds all items with Name=D-100 to the current selection.

There are no error messages for broken links, for example due to a typo.

In Excel you can use the “CONCATENATE” and “HYPERLINK” functions to easily build a list of links.

Enter your model URL or path and a column for attributes, values and commands you want to include:

Paths might not work if they contain special characters. Use an URL encoder for paths to ensure them being correct.

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 …

Then add a function with the following structure:

=HYPERLINK(CONCATENATE(“upvapi://”;$B$1;“?”;A4;“=”;B4;“&”;C4))

Table 1: Commands

Command Description
ClearClipping Disables clipping
ClearColor Restores the initial object colours.
ClearCustomAttributes Reset all changes to custom attributes in this session.
ClearHighlight Disables highlighting
ClearLinks Removes LinkFile links
ClearSelection Unselects all selected objects
Color Color=[html color code] (format #RRGGBB or #RRGGBBAA) Example: CMD!Color=#FF0000
Combine Combine=[OR/AND] Use “OR” if you want to use the operator “OR” between query conditions instead of “AND” (default).
ExportPackageFile Exports package-files to the specified path.
Fit Optional parameters: Centred. true (standard): fit to centre of the box. false: fit to the screen borders of the current view. Example: CMD!Fit=true
Highlight Highlights the specified object Example: Name=D-100&CMD!Highlight
IntelliClip IntelliClip=[distance in meters] Values >0 will display only the object. 0 will also display objects touching the selected object. You can use values with a decimal point.
LoadColorFile

LoadColorFile=[online or offline location] local: CMD!LoadColorFile=C:\colors.xlsx via http: CMD! LoadColorFile=http://sdfsdf.sdfsd.sdfsd ….

via UNC: CMD!LoadColorF ile=file://////server/share/colors.xlsx

Note: For UNC it is important to use 6 slashes “//////” after “file”.

Examples:

CMD!LoadColorFile=c:\colors.xlsx CM D!LoadColorFile=http://demo.universalpl antviewer.com/demoPlant/4/0/colors.xlsx
LoadConfigFile Loads a configuration file. Parameters: Configuration file name Combine mode (optional). Sets handling of existing settings. By default set-tings are cleared: Merge (existing views will be merged and not cleared. Overrides existing values with the values of the configuration file) Example: C:/config.upv!Merge
LoadLinkFile

LoadLinkFile=[online or offline location]

local:CMD!LoadColorFile=C:\colors.xlsx

via http: CMD! LoadColorFile=http://sdfsdf.sdfsd.sdfsd … via UNC: CMD!LoadColorFile=file://////server/share/colors.xlsx Note: For UNC it is important to use 6 slashes “//////” after “file”.
LoadPackageFile

Loads package files from a specified path.

Parameters: URL Replace (optional) If set true, replaces current packages instead of adding them to existing ones. Example: CMD!LoadPackageFile=c:\package.upvf!true
LoadSketch Loads a sketch from the specified path. A second parameter renames the sketch. Example: CMD!LoadSketch=C:\Sketch\SketchFile.upvsk!NewName
ResetView Resets the camera mode, the camera’s position, its rotation and states like highlights to how it was when the model was loaded.
SearchFallback

This command automatically adds the search string to the search box. If the exact search doesn’t return any results a fuzzy search will be started automatically.

Example: upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=E240&NozzleName=N8&CMD!Select&CMD!Fit&CMD!Searchfallback

This will start a search an find the Nozzle N8 of the equipment E-240
Select Selects the specified object Example: Name=D-100&CMD!Select
SetCameraView SetCameraView= [X!Y!Z!rotationX!rotationY!rotationZ] (Euler angle) Example: CMD!SetCameraView=3037!2476!72!180!180!90 sets the camera to the coordinates 3037 (X), 2476 (Y), 72 (Z = height) facing parallel to the ground rotated 90° to the left.
SetCameraViewLookAtTarget SetCameraViewLookAtTarget=[X!Y!Z!TargetX!TargetY!TargetZ] Moves the camera to the specified location lets it face the target location.
SetClippingPlane Sets the visible Camera-view-distance. The first parameter is the minimal distance of viewable objects, the second is the maximum distance. Example: CMD!SetClippingPlane=20!30
SetTreeConfiguration SetTreeConfiguration=[discipline!discipline…] Example: CMD!SetTreeConfiguration=Task!SystemPath
SetVisibility SetVisibility=[True/False]
SetVisibleAspects SetVisibleAspects=[aspect!aspect]| Example: CMD!SetVisibleAspects=Simple Physical! Insulation to show both insulation and simple physical.
ShowOnly Sets the visibility of all query objects to visible and hides all other objects.
ShowMessage Shows a message and title in a messagebox.
Example: CMD!ShowMessage=Your Message!Your Title
TakeAndSaveScreenshot

Takes a screenshot with the following parameters in order:

Path where the image is to be stored

Width in pixel Height in pixel Field of view in degree (above 160 might produce wrong images) Format, either .png or .jpg Hide UI, true or false Enable antialiasing, 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 meters] Values < 0 will be treated as 0. You can use values with a decimal point.
VolumeClipByCoordinates Runs the volume clip algorithm with a bounding box defined by the parameters: X min Y min Z min X max Y max Z max Example: CMD! VolumeClipByCoord inates=-10.0!-10.0!-10.0!20.0!20.0!20.0

Wildcards:

  • * = any character

  • _ = any single character

Condition operators

By default query conditions are combined with AND:

Name=K-001&Nozzle Name=N5

OR is possible with the combine command:

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

API module

With the UniversalPlantViewer API external applications can send queries via URI or TCP to UniversalPlantViewer. You can integrate UniversalPlantViewer in any software.

Using the API module requires an API licence.

Queries

You can use all deep linking commands with wildcards and additional commands.

Use the Combine command to switch between AND / OR. After starting UniversalPlantViewer AND is the default value but it will not return to that automatically.

Table 2: TCP commands

Commands Description
GetCameraView Returns the current camera view.
GetClippingInfo Returns coordinates of snapping-points and -lines of specified objects
GetModelInfo

Returns a dictionary describing all loaded models by

  • Model URI

  • List of all available attribute names

  • List of all available aspect names.
GetObjects Returns a list of all object UIDs.
GetObjectsAttributes Returns a dictionary for each object containing its attributes. (Optional parameter: a list of attribute names). Example parameters: Name!Task
GetObjectsBoundingBox Returns the bounding box for each object.
GetObjectsColors Returns a dictionary for each object containing aspect name and default/current colour.
GetObjectSnapInfo Returns coordinates of snapping-points and -lines of specified objects
GetSelectedObjects Returns a list of all selected object UIDs
GetVisibleAspects Returns all visible aspects
PlaceArc Places an arc
PlacePly Places a polygon

TCP commands and their parameters are defined in the UniversalPlantViewerApi.dll

Table 3: General TCP parameters

These parameters are located in the ParameterBase class and can be combined with every other command.

Parameter Description
ClippingFilter Limits the query to elements contained in specific clippings Corresponds to GetClippingInfo.
IntelliPidDrawingFilter Limits the query to elements in specific IntelliPIDs.

Using JSON via TCP

The UniversalPlantViewer starts a TCP server (IP 127.0.0.1, listening to port 40123; the port can be changed via command line parameters) and can process simple JSON messages.

To start the communication, send the following initial message:

Field Description Type
Header “UPVAPI1\n” UTF-8 String

Table 4: Event callback registering

Command Description Example
AddEventCallback Registers a new callback for the specified event name. The event callback has its RequestId set to the RequestId specified by the second parameter. Parameters: - Event name - RequestId (must not be used for other event callbacks) SelectionChanged!1000
RemoveEventCallback Unregisters a callback with the matching RequestId. Parameters: -RequestId 1000

Table 5: Events (TCP)

Command Description Example
LinkClicked Is called after the user clicked an url link. By prefixing a link url with “event:” only the event is triggered without actually opening the link in the browser. "LinkClicked": { "Url":"http://www.caxperts.com/", "Template": "http://www.caxperts.com", "AssociatedObject": "0001388c-0000-0000-8bf3-55d0615a1e10"}
SelectionChanged Is called after the list of selected objects changed. Returns a list with the UIDs of objects in the new selection. "SelectionChanged":["00004e23-0000-0000-0080c0fc06552004"]
PointerClicked Is called after the user clicked somewhere in the model. Returns a dictionary with the position of the click within the window and the mouse button that was pressed. The mouse position origin is at the bottom left. Possible mouse button names: - Left - Middle - Right "PointerClicked": {"Button": "Right", "X": 323, "Y": 549}

Table 6: Message protocol definition

Field Description Type
Message length The number of bytes in the message. Unsigned Integer (4 Byte) in Network Byte Order
Message The JSON text UTF-8 String

Table 7: JSON request definition

Field Description Type
Model The URL of the model. Commands will be executed for this model only. If missing, commands will be executed for all models. String
Condition The object request in query syntax. String
ConditionCombineMode Sets the combine mode for querieswith several conditions. If not specified or set to AND, the conditions will be combined using AND. If set to OR, the conditions will be combined using OR. String
Command The command to beexecuted. String
RequestId A unique number that allows linking answers to requests. If not specified, “-1” is assumed. Integer
CommandParameters Used to set command parameters. List of String, Integer and Floats.

JSON Example:

{
    "Model" : http://demo.universalplnatviewer.com/DemoPlant/3/",
    "Condition" : "Task=Equipment",
    "Command" : "Fit",
    "RequestId" : "1000",
    "ConditionCombineMode" : "OR",
    "CommandParameters" : \[ "True" \]
}

Table 8: JSON response

Field Description Type
ErrorCode Contains the error code (0 = no error) Integer
ErrorMessage Contains the error description (empty = no error) String
RequestId Contains the RequestId that was transmitted in the query (-1 = standard, none transmitted) Integer
ResultData Contains the result of Get commands Dictionary <String, Object>
Object depends on the Get command.

Example:

{
    "ErrorCode" : 0,
    "ErrorMessage" : "OK",
    "RequestId" : -775527921,
    "ResultData" : {
    }
}