## Tutorial 2 - Simple custom instrument

Please read the tank tutorial first in order to understand the basic functions of **3D SymbolDesigner**, especially how to add, rename, and edit nodes.

In this tutorial, you will build a custom instrument part with two nozzles, a handwheel, and insulation for both the body part and the nozzles.

> Piping symbols use a right-handed coordinate system with the Y-axis pointing upwards in SmartPlant 3D. There are exceptions to this rule, for example three-way valves with an integral operator.

<img src="./media/image40.png" width="750" height="543">

### Create a new project

1.  Click (<img src="./media/2_image19.png" width="16" height="16">) to create a new symbol project.

2.  Change the coordinate system orientation by pressing the **Y-Axis up** button (<img src="./media/image112.png" width="16" height="16">).

### Add parameters

3.  Select the Parameters item in the menu tree. Then click five times on the parameter button (<img src="./media/image82.png" width="16" height="16">).

<img src="./media/image42.png" width="410" height="253">

4.  Rename the parameters: click `Parameter1`, press **F2** if needed, and enter **parFacetoFace**. Repeat this for `Parameter2` to `Parameter5` with **parActuatorHeight**, **parActuatorDiameter**, **parStemWidth**, and **parInsulationThickness**.

<img src="./media/image43.png" width="410" height="252">

5.  The table of variants should now look like:

><img src="./media/image44.png" width="750" height="92">

6.  Now enter the default values for the parameters in the table:

><img src="./media/image45.png" width="750" height="93">

7.  Rename the variant **Default** to **MyCustomInstrument**:

><img src="./media/image46.png" width="750" height="88">

8.  Rename the SmartPlant 3D parameter mappings: select the `Parameter1` cell and right-click it. In the context menu, select **Set SmartPlant 3D attribute**. Choose the correct attribute from the list, check **Occurrence attribute**, and press **Apply**. Add `OA:` in front of the parameter name if the parameter is an occurrence attribute, that is, an attribute that can be modified at runtime in SmartPlant 3D. Repeat this for `Parameter2` to `Parameter5`. **3D SymbolDesigner** checks the spelling. The parameters are now valid and the background colour changes to green:

><img src="./media/image47.png" width="750" height="51">

### Add PipingPorts

9.  Expand the **PipingPort parameter collection** toolbar icon (<img src="./media/image48.png" width="16" height="16">) and click **Piping port (bolted preset)**. One `PipingPort` will be added to the tree view and the list of variants. Repeat the step once more to add a second one.

<table>
<tr><td>

<img src="./media/image49.png" width="429" height="265">

</td><td>

<img src="./media/image50.png" width="238" height="90">

</td></tr>
</table>

### Add nozzles

10. Click twice on the button for piping connectors (<img src="./media/image51.png" width="16" height="16">). Press **F2** to rename the first nozzle node to **VNoz1** and the second to **VNoz2**.

11. Rotate **VNoz1** by 180 deg about the z axis.\
    ![](./media/image52.png)

12. Move `VNoz1` to one end of the instrument by typing the following
    into its Translation.X subnode:\
    \- parFacetoFace / 2 - PipingPort1.FlangeProjectionOrSocketOffset +
    PipingPort1.FlangeProjection +
    PipingPort1.SeatingOrGrooveOrSocketDepth.

13. Move `VNoz2` to the other end of the instrument by typing the
    following into its Translation.X subnode:\
    parFacetoFace / 2 + PipingPort2.FlangeProjectionOrSocketOffset -
    PipingPort2.FlangeProjection -
    PipingPort2.SeatingOrGrooveOrSocketDepth.

### Add graphical primitives

14. Click twice on the cone button
    (<img src="./media/image53.png" width="16" height="16">), once on sphere (<img src="./media/image54.png" width="16" height="16">), once on torus (<img src="./media/image55.png" width="16" height="16">) and four times on cylinder (<img src="./media/image135.png" width="16" height="16">).\
    <img src="./media/image56.png" width="375" height="216">

15. Rename Cone1 to **Body1**, Cone2 to **Body2**, Sphere1 to **Body3**, Torus1 to **HandWheel**, Cylinder1 to **Stem**, Cylinder2 to **InsBody**, Cylinder3 to **InsCylinderVNoz1** and Cylinder4 to
    **InsCylinderVNoz2**.\
    <img src="./media/image57.jpg" width="340" height="457">

16. Right-click the **InsBody** node, select **Properties** from the context menu, and change the aspect from **SimplePhysical** to **Insulation**. Repeat this for **InsCylinderVNoz1** and **InsCylinderVNoz2**.

    <img src="./media/image58.png" width="328" height="226">

17. Unselect all created primitives, except Body1 and Body2, using the checkbox in front of them.

18. Change to S/E isometric view as shown on the picture below.\
    <img src="./media/image138.png" width="94" height="85">

### Parameterise the primitives

19. Expand the **Body1** node and the **Geometry** subnode and type in the following formula as value for the cone's length (L1) property:\
    **parFacetoFace / 2 - PipingPort1.FlangeOrHubThickness - PipingPort1.FlangeProjection**

20. Change the value of the cone's first diameter, `D1`, in the same node to **0.001**. A distance value must not be zero, because SmartPlant 3D cannot handle zero-distance values.\
    <img src="./media/image60.png" width="337" height="144">

21. Type in the following as value for the D2 property:\ **PipingPort1.PipingOutsideDiameter**.

22. Expand the Body2 and underlying Geometry node and set the value of L1 to:\
    **parFacetoFace / 2 - PipingPort2.FlangeOrHubThickness - PipingPort2.FlangeProjection**

23. Change the value of D1 to **0.001**.

24. Set the value of the cone's second diameter (D2) to **PipingPort2.PipingOutsideDiameter**.

25. Rotate Body2 by typing **180 deg** into its Rotation.Z property.

26. Use the zoom-in tool (<img src="./media/image139.png" width="16" height="16">) until the two cones fit in the view. It should now look like this:\
    <img src="./media/image62.png" width="751" height="453">

27. Expand the Body3 and the appropriate Geometry subnode to change the diameter value (D1) to the average outside diameter of the pipe by typing:\
    **(PipingPort1.PipingOutsideDiameter + PipingPort2.PipingOutsideDiameter ) / 2**.

28. Change the L1 value of the Stem primitive to **parActuatorHeight**.

29. Set the Stem's diameter (D1) to **parStemWidth**.

30. Rotate the Stem by assigning **90 deg** to its Rotation.Z property.

31. Change the Value of the Handwheel's D1 property to **parStemWidth**.

32. Type in the formula **(parActuatorDiameter - parStemWidth) / 2** for the Handwheel's radius (R1).

33. Set its angle (A1) property to **360 deg**.

34. Expand the Handwheel's Rotation subnode and set X to **90 deg**.

35. Open the Translation branch and type in **parActuatorHeight - parStemWidth / 2** for the Y value.

36. Set Z to **-Geometry.HandWheel.Geometry.R1**.

37. Switch on the checkboxes for **Body3**, **Handwheel**, and **Stem**, then zoom out until the instrument fits in the viewport.\
    <img src="./media/image63.png" width="396" height="236">

    You should now see something like this:\
    <img src="./media/image64.png" width="231" height="295">

38. Expand InsBody and its subnode Geometry to set its length L1 to:\
    **Geometry.Body1.Geometry.L1 + Geometry.Body2.Geometry.L1**

39. Assign the formula **Max(Geometry.Body1.Geometry.D1, Geometry.Body2.Geometry.D1) + 2 \* parInsulationThickness** to its D1 property.

40. Expand the Translation subnode and set X to **-Geometry.Body1.Geometry.L1**.

41. Change to the InsCylinderVNoz1 primitive and expand its subnode Geometry. Change the value of L1 to **PipingPort1.FlangeOrHubThickness + parInsulationThickness**.

42. Type the formula **PipingPort1.FlangeOrHubOutsideDiameter + 2 \* parInsulationThickness** in D1.

43. Move this cylinder by changing its Translation.X property to **-parFacetoFace / 2 + PipingPort1.FlangeProjection**.

44. Expand the branch InsCylinderVNoz2 and the underlying Geometry node. Assign the formula **PipingPort2.FlangeOrHubThickness + parInsulationThickness** to the L1 value.

45. Set **PipingPort2.FlangeOrHubOutsideDiameter + 2 \* parInsulationThickness** for the D1 property.

46. Move the cylinder by setting **Geometry.Body2.Geometry.L1 - parInsulationThickness** for X.

47. Tick all the remaining unchecked primitives. Now the viewport should look like this:

    <img src="./media/image65.png" width="366" height="409">

### Export to SmartPlant 3D 

48. The symbol is now ready to be exported to SmartPlant 3D. Save it first, and then click the toolbar button (<img src="./media/image29.png" width="16" height="16">) to export it.

49. Optionally, press the **Reload** button. The catalogue structure is then loaded from the SP3D database. This works only if a valid SP3D database server is available and configured, see item 52.

50. Add a new node below the `Catalogue-Piping-Custom Instruments` node, select it, enter a suitable key and description, and then select it again.

51. On the second tab, **Build**, choose your target directory. You may also tick the **Compile project** checkbox under **Compiler settings**. This works only if the required SP3D libraries (`.dll`) are registered and Visual Basic 6 is installed on this machine.

52. Click the **Start** button. Before the export begins, **3D SymbolDesigner** checks whether the parameters and the variant names used are valid, see *Naming rules*. This helps to avoid errors during the bulkload process afterwards. Any errors that occur are shown in the **Error list** tab. Clicking an item in the list moves the cursor to the corresponding cell in the table.

53. Optionally: Export of a **3D PDF datasheet** (see: *Export of a 3D PDF datasheet*).

54. Start the Bulkload tool and load the DLL. In most cases, the option *Append to existing catalog* must be selected for this purpose.\
    <img src="./media/image34.jpg" width="640" height="720">

55. Check the log file for critical errors.

> The warning *Failed to set the SymbolIcon property* is only an informative message. It does not affect the usability of the symbol.

56. Now you are able to use the symbol in SmartPlant 3D.

<img src="./media/image67.png" width="616" height="324">

<img src="./media/image40.png" width="750" height="543">