Example Scripts
================

The ``scripts/`` directory contains ready-to-run example scripts demonstrating the
routing library across a range of scenarios. All scripts are self-contained and can be
run directly after installing ``routing``.

.. contents:: On this page
   :local:
   :depth: 1


Simple Test Cases (``scripts/simple_test_cases/``)
---------------------------------------------------

These scripts use a small window-frame assembly (``data/step/Cas_test_windows_V5.step``)
and are the best starting point.

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Script
     - Description
   * - ``window_test_case.py``
     - **Start here.** Full routing workflow: load STEP file, define pipe types and
       ports, build a CadMap, run pathfinding (A*), visualize results, run optimization.
       Matches the :doc:`tutorials/basic_routing` tutorial.
   * - ``window_test_case_multi.py``
     - Multi-grid version of the window test case. Uses
       :class:`~routing.core.cadmap.MultiCadMap` without scale-factor changes. Includes
       bifurcation point detection.
   * - ``window_test_case_multi_scale.py``
     - Multi-scale version (``size_factor=3``). Shows hierarchical voxel meshes with
       sub-grid connections and demonstrates routing at multiple resolution levels.
   * - ``shaped_zone_example.py``
     - Demonstrates all four ``ShapedWeightingRule`` zone types: attractive (cone),
       repulsive (box), forbidden (box), and forced (box). Matches the
       :doc:`tutorials/shaped_zones` tutorial.
   * - ``shaped_zone_example_multi.py``
     - Multi-grid version of the shaped zones example.
   * - ``shaped_zone_example_multi_scale.py``
     - Multi-scale (3-level hierarchy) version of the shaped zones example.
   * - ``constraint_rules_example.py``
     - Demonstrates constraint rules: ``ClampingConstraint``, ``GravityRule``,
       ``StraightLengthRule``, ``DistanceAttributeToggler``, and a custom
       ``UserDefinedConstraint``. Matches the :doc:`tutorials/design_rules` tutorial.
   * - ``large_room_with_obstacles.py``
     - Routing in a large space with multiple obstacles using the multi-scale approach.
       Useful reference for real-size assemblies.
   * - ``window_input_data.py``
     - Input data module shared by many test scripts: defines multiple pipe types and
       their port configurations. Import as a module rather than running directly.


Pathfinding Examples (``scripts/pathfinding/examples/``)
---------------------------------------------------------

These scripts use the standalone ``routing.pathfinding`` module directly — no CAD file
or design rules required.

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Script
     - Description
   * - ``03_view_map.py``
     - Loads a pre-computed numpy map (``scripts/grit_test_case/grit_cad.npy``),
       finds an A* path, and visualizes it in 3D using Open3D. Good starting point for
       pathfinding-only use cases.
   * - ``04_theta_star.py``
     - Side-by-side comparison of Theta* and A* on the same 3D obstacle map. Displays
       path cost, length, and interactive 3D visualization with Plotly.


Otter Test Cases (``scripts/otter_test_cases/``)
-------------------------------------------------

More complex test cases based on a multi-part assembly with static and mobile parts.

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Script
     - Description
   * - ``DAR_test_case.py``
     - Advanced routing with multiple pipe types, pooling rules, and turn penalties.
       Generates multiple routing solutions and runs simulated annealing optimization.
   * - ``DAR_test_case_multi_grid.py``
     - Multi-grid version of the DAR test case using ``MultiCadMap.from_cad_maps``.
   * - ``DAR_test_case_multi_scale.py``
     - Multi-scale version with hierarchical resolution levels.


Building Test Case (``scripts/building_test_case/``)
-----------------------------------------------------

Routing in a building-scale environment with both pipes and cables.

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Script
     - Description
   * - ``building_test_case.py``
     - Sets up a room with obstacles, configures design rules, and routes both pipes
       and cables. Demonstrates mixed pipe/cable routing.


GRIT Test Case (``scripts/grit_test_case/``)
---------------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Script
     - Description
   * - ``GRIT_test_case.py``
     - Complex routing scenario with many interconnected cables. Extracts ports from
       CAD geometry automatically, creates specifications programmatically, and runs
       multi-iteration optimization.


Running the Scripts
-------------------

All scripts expect to be run from the repository root or the script's own directory.
Most scripts use relative paths to data files:

.. code-block:: bash

   # From the repository root
   python scripts/simple_test_cases/window_test_case.py

   # Or from the script's directory
   cd scripts/simple_test_cases
   python window_test_case.py

**Data files** used by the scripts:

- ``data/step/Cas_test_windows_V5.step`` — window frame assembly (simple test cases)
- ``data/step/inner_window.step``, ``data/step/outer_window.step`` — inner/outer window bodies
- ``scripts/grit_test_case/grit_cad.npy`` — pre-computed occupancy grid for pathfinding examples
- ``scripts/otter_test_cases/data/3DTUYDessia.stp`` — Otter assembly

**Optional dependencies** (not installed by default):

- ``open3d`` — required for ``03_view_map.py`` visualization
- ``plotly`` — required for ``04_theta_star.py`` visualization