User Guide: Routing Workflows
==============================

A **workflow** is a pre-defined sequence of routing operations — voxelization, path
generation, optimization — packaged so that they can be re-run consistently with
different inputs.

``routing`` provides workflow definitions as JSON configuration files in
``scripts/workflows/``. These are primarily intended for integration with the
`Dessia <https://dessia.io>`_ platform and batch processing pipelines.

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


Typical Workflow Structure
--------------------------

A standard routing workflow follows this sequence:

.. code-block:: text

   1. Load CAD file (STEP/STP)
          ↓
   2. Build RuledVolumes (attach design rules to each CAD volume)
          ↓
   3. Build CadMap (voxelize + compute distance fields)
          ↓
   4. Generate paths  (RoutePlanner.generate)
          ↓
   5. Optimize geometry (RoutePlanner.optimize)
          ↓
   6. Export results (visualization, CSV, or serialized objects)

Each step corresponds to a section in the :doc:`../tutorials/basic_routing` tutorial.
For a reusable Python workflow, encapsulate these steps in a function:

.. code-block:: python

   def run_routing_workflow(step_file: str, port_file: str, voxel_size: float):
       """Full routing workflow."""
       from volmdlr.step import Step
       from volmdlr.model import VolumeModel
       from routing.core.cadmap import CadMap
       from routing.core.core import Port, RuledVolume, Specification
       from routing.core.design_rules import TurnPenalizer, WeightingRule
       from routing.core.finders import SmartFinder
       from routing.core.optimizer import Costs, Settings
       from routing.core.route_planner import RoutePlanner

       # 1. Load CAD
       model = Step.from_file(step_file)
       volume_model = model.to_volume_model()

       # 2. Build RuledVolumes
       weighting = WeightingRule("linear", 0.0, 0.2, 1, 10)
       ruled_volumes = [
           RuledVolume.from_volume_model(VolumeModel([prim]), [weighting], name=f"vol_{i}")
           for i, prim in enumerate(volume_model.primitives)
       ]

       # 3. Build CadMap
       bounding_box = CadMap.build_bounding_volume(ruled_volumes, [], voxel_size)
       cadmap = CadMap.from_project_inputs(
           design_rules=[TurnPenalizer(cost=3.0)],
           ruled_volumes=ruled_volumes,
           bounding_box=bounding_box,
           voxel_size=voxel_size,
           exact_distances=True,
       )

       # 4. Load ports and build specifications
       with open(port_file, "rb") as f:
           ports = Port.from_xlsx_stream(f)

       # (pair and build specifications as needed)
       # ...

       # 5. Generate + Optimize
       route_planner = RoutePlanner(cadmap, SmartFinder("AStar", "manhattan", "never"))
       result = route_planner.generate(specifications=specifications, n_iterations=1)

       costs = Costs(length=1000, sideways=100, short_line=5000,
                     gravity=5000, bend=250, constraints=5000, interferences=1e8)
       settings = Settings(voxel_size=0.01, max_shift=0.1, n_iterations=3, max_iter=1000)
       result = route_planner.optimize(costs=costs, settings=settings, picked_path="best")

       return result


Workflow JSON Files
-------------------

The ``scripts/workflows/`` directory contains pre-built workflow configurations for
the Dessia platform:

.. code-block:: text

   scripts/workflows/
   ├── Generation/
   │   ├── run_cad_mapping_and_generation_en.json
   │   └── run_cad_mapping_and_generation_fr.json
   └── Mapping/
       ├── build_ruled_volume_en.json
       └── build_ruled_volume_fr.json

These JSON files encode the full routing pipeline as a directed acyclic graph of
Dessia method calls. They are uploaded to the Dessia platform and executed there.
They are not intended to be run directly with Python.

For standalone Python use, follow the :doc:`../tutorials/basic_routing` tutorial
instead.


Next Steps
----------

- :doc:`../tutorials/basic_routing` — step-by-step tutorial for the full workflow
- :doc:`results_access` — reading and exporting routing results
- :doc:`../tutorials/port_import_excel` — loading ports from spreadsheets