.. _cad_tutorial:

CAD Modeling
============

Before generating solid or mesh models, see the tutorial :ref:`mechanism_with_tool` which explains
how the line model of the mechanisms look like in the backend and how the design parameters can be
generated.

Generating CAD Models
---------------------

There are three methods for exporting the mechanism as a mesh or solid model. The Python libraries
``build123d`` are required for STEP files generation, while
``trimesh`` and ``manifold3d`` are required for STL generation. You can install them using pip:

.. code-block:: bash

    pip install build123d trimesh manifold3d


:meth:`.RationalMechanism.export_single_mesh()` returns an STL mesh file of the whole mechanisms. Similarly,
:meth:`.RationalMechanism.export_single_solid()` returns a STEP file. In both cases, the mechanism bodies
are merged in a single body. An interactive visualization of the method
:meth:`.RationalMechanism.export_single_solid()` STEP file can be seen here:

.. raw:: html

   <script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>
   <model-viewer src="../_static/mechanism.glb"
        alt="Visualization of STEP generated mechanism"
        auto-rotate camera-controls
        environment-image="neutral"
        shadow-intensity="1"
        style="width: 100%; height: 50vh;">
   </model-viewer>

Alternatively, the method :meth:`.RationalMechanism.export_solids()` returns a STEP file that consists of
assembled solids, i.e. the every link is one part (the joints of two links overlap).
When importing in your CAD, keep in mind to import it as assembly.

All methods accept various arguments for customization of the output. For example,
they accept arguments for size of the joints and links cylinders, and also can
add the tool link and frame meshes. Be careful with units (e.g. in :meth:`.RationalMechanism.export_single_solid()`)
it has to be specified if the result and inputs are in millimeters or meters.

.. literalinclude:: /examples/d_t_cad_export.py
    :language: python

.. _stl_preview-motion_designer:

Visualizing Custom STL in MotionDesigner
----------------------------------------

Any STL file can be imported as solid body in :ref:`motion_designer`. This can be useful for visualizing
the mechanism in the context of the task, e.g., your work-cell.

It is better if the STL file coordinates are already in the world frame
(``p0`` of your mechanism in MotionDesigner), however you can use the ``transform`` argument to place it wherever needed.
Place the STL file in the same directory as your script and use the following pattern:

.. literalinclude:: /examples/d_t_cad_stlvis.py
    :language: python

.. figure:: figures/cad_scene.png
    :width: 480 px
    :align: center
    :alt: MotionDesigner scene with rendered STL


The scene will look similar to the figure above.
As you can notice, argument ``preview_mechanism`` is set to ``True``. This will visualize
the mechanism in the MotionDesigner window, so you can check if the size and position of the mechanism is
adequate in the context of your task. However, the previewing has impact on rendering performance. Also,
keep in mind that this design can be changed by dragging the physical connection points along joint axes,
so the preview is supposed to be only informative.