.. _python_api_compute_obb:

.. currentmodule:: flow360

******************************************
Estimate a wheel rotation axis with an OBB
******************************************

This example shows how to use the draft context to fit an oriented bounding box
(OBB) to a set of wheel surfaces, then read back the estimated rotation axis,
center and radius. These values can be used to configure a rotating wall
boundary condition or a rotating reference frame without measuring the geometry
by hand.

.. code-block:: python

    import flow360 as fl

    project = fl.Project.from_cloud("PROJECT_ID_HERE")
    geometry = project.geometry

    with fl.create_draft(
        new_run_from=geometry,
        face_grouping="face_grouping_tag",
    ) as draft:

        # Select the surfaces that make up the wheel.
        wheel_surfaces = draft.surfaces["wheel_*"]

        # Fit the oriented bounding box to those surfaces.
        # rotation_axis_hint is optional; when omitted the axis with the most
        # circular cross-section is chosen automatically.
        obb = draft.compute_obb(wheel_surfaces, rotation_axis_hint=[0, 1, 0])

        print("center:", obb.center)
        print("rotation axis:", obb.axis_of_rotation)
        print("radius:", obb.radius)

Notes
=====

- ``compute_obb`` is available only for drafts created from a **Geometry** asset. Drafts created from a surface mesh or volume mesh do not carry the tessellation data required to fit the box.
- ``entities`` accepts a single surface, a list of surfaces, or a surface view (e.g. ``draft.surfaces[...]``). Non-surface entities (for example mirrored surfaces) are skipped with a warning.
- ``rotation_axis_hint`` biases the axis selection toward a known direction. When omitted, the axis whose perpendicular cross-section is most circular is used.
- The returned ``OBBResult`` exposes ``center``, ``axes``, ``extents``, ``axis_of_rotation`` and ``radius``. When the project has a length unit, the dimensioned fields (``center``, ``extents`` and ``radius``) carry that unit.

Example use cases
=================

- Automatic rotation setup for wheels and other cylindrical components
- Estimating component size and orientation directly from geometry

.. seealso::

   - :ref:`Draft API Reference <python_api_draft>` (details of ``DraftContext.compute_obb`` and ``OBBResult``)
   - :ref:`Asset Drafts user guide <asset_drafts_userGuide>` (conceptual overview)