# LaserscanClippingPlugin

**LaserscanClippingPlugin** is a plugin used in UniversalPlantViewer Builder to manipulate laser scan data for UniversalPlantViewer.
It uses UPV session files (`.upvc`) exported from UniversalPlantViewer and merges clipping information with the original session file.

## Setup procedure

LaserscanClippingPlugin is not an executable plugin and does not include a setup routine. After downloading the file, extract the contents of the ZIP archive to the following directory:

`%AppData%\CAXperts\Universal Plant Viewer Builder\Plugins\`

If the `Plugins` folder does not exist, create it manually.

## Clipping Definitions

## Create Clipping Objects

Before clipping, the clipping areas must be defined in UniversalPlantViewer by using sketching objects. To create a new sketch, select the Sketching function from the main menu.

<img src="./media/LaserScanClippingPlugin_image6.png" width="32" height="187">

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.

<img src="./media/LaserScanClippingPlugin_image7.png" width="248" height="185"> 

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.

<img src="./media/LaserScanClippingPlugin_image8.png" width="36" height="168">

<img src="./media/LaserScanClippingPlugin_image9.png" width="740" height="420">

## 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.

<img src="./media/LaserScanClippingPlugin_ClippingModeDrowpdown.png">

## 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.

<img src="./media/LaserScanClippingPlugin_image15.png" width="728" height="643">

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.

<img src="./media/LaserScanClippingPlugin_image16.png" width="668" height="587">

After saving the sketch as a `.upvc` file and building it with UniversalPlantViewer Builder, only the laser scan elements within the clipping box remain.

<img src="./media/LaserScanClippingPlugin_image17.png" width="772" height="653">

## 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.

<img src="./media/LaserScanClippingPlugin_image20.png" width="728" height="643">

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.

<img src="./media/LaserScanClippingPlugin_image21.png" width="727" height="546">

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.

<img src="./media/LaserScanClippingPlugin_image22.png" width="757" height="606">

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.

<img src="./media/LaserScanClippingPlugin_image10.png" width="300" height="240">

## 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.

<img src="./media/LaserScanClippingPlugin_image18.png" width="673" height="434">

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.

<img src="./media/LaserScanClippingPlugin_image9.png" width="739" height="629">
 
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.

<img src="./media/LaserScanClippingPlugin_image19.png" width="746" height="639">

## 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`

<img src="./media/LaserScanClippingPlugin_Update.png" width="599" height="193">

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.

<img src="./media/LaserScanClippingPlugin_image25.png" width="730" height="171">

## 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.

<img src="./media/LaserScanClippingPlugin_image26.png" width="736" height="358">

## 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]**.

<img src="./media/LaserScanClippingPlugin_image27.png" width="728" height="491">

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.

<img src="./media/LaserScanClippingPlugin_image28.png" width="727" height="464">

## 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]**.

<img src="./media/LaserScanClippingPlugin_image29.png" width="739" height="352">

## 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]**.

<img src="./media/LaserScanClippingPlugin_image30.png" width="739" height="352">

## Output

Run UniversalPlantViewer Builder as usual. The resulting UPV contains the final clipped model.