Add z-level routing option (Rust)

[ppinchuk]

Add logic for z-level routing on Rust side. Minimally wire up Python side so that it still works. Upcoming PR will fully wire up the Python side.

[Copilot]

Pull request overview

This PR introduces multi-option (“z-level”) routing support in the Rust routing core by extending routing state with an option dimension and updating the cost-function schema to define per-option layer stacks. It also minimally updates the Python/CLI surfaces and tests to continue working with the new Rust-side schema (using a "default" routing option).

Changes:

• Added an option dimension to routing indices and updated routing/search infrastructure to operate on (row, col, option) states, including same-pixel option transitions.
• Reworked Rust cost-function parsing to require routing_options (per-option layer definitions), plus optional drivers and transition_costs.
• Updated Python-side cost JSON generation, CLI cost-building, and test fixtures to nest layers under routing_options.default.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/rust/integration_tests.rs	Updates Rust integration tests for routing_options.default JSON and new index constructor.
tests/python/unit/test_skimage_validate.py	Wraps cost definitions under routing_options.default for unit tests.
tests/python/unit/test_rust_bindings.py	Updates Rust binding unit tests to use routing_options.default-scoped config.
tests/python/unit/routing/test_routing_base.py	Adjusts assertions to match normalized barrier layers nested under routing_options.default.
tests/python/unit/routing/cli/test_routing_cli_build_costs.py	Updates CLI config fixtures and adds routing_option="default" to calls.
tests/python/integration/test_rust_bindings_integration.py	Updates integration tests for nested routing option config.
revrt/utilities/handlers.py	Improves docstring for layer_attrs return description.
revrt/routing/cli/utilities.py	Updates routing-layer hash payload to match new cost schema nesting.
revrt/routing/cli/build_costs.py	Requires routing_option and reads cost/friction/barrier layers from the chosen routing option.
revrt/routing/base.py	Emits cost-function JSON with routing_options.default wrapping.
revrt/costs/cli.py	Fixes debug logging to use the correct serialized_build_config variable.
crates/revrt/src/routing/scenario.rs	Adds driver/transition-cost support and option-transition neighbors; adds allowed-states helper.
crates/revrt/src/routing/mod.rs	Validates start state against allowed states and passes updated grid shape; contains commented-out alternative logic.
crates/revrt/src/routing/long_range.rs	Propagates (rows, cols, options) grid shape through long-range algorithms and tests.
crates/revrt/src/routing/astar.rs	Updates tests and adds layered-option heuristic/successor coverage.
crates/revrt/src/routing/algorithm.rs	Updates algorithm interface to accept (rows, cols, options) grid shape.
crates/revrt/src/network/unused.rs	Updates tests to use new index constructor.
crates/revrt/src/network/long_range/utilities.rs	Extends grid indexing to include option dimension and updates tests.
crates/revrt/src/network/long_range/mod.rs	Threads option-aware grid shape/indexing through search states and tests.
crates/revrt/src/network/cost.rs	Updates tests for new index constructor.
crates/revrt/src/lib.rs	Extends ArrayIndex with option, adds tuple conversions, and updates tests and sample JSON.
crates/revrt/src/ffi/mod.rs	Updates FFI to build indices via new_ij; adds TODO comment.
crates/revrt/src/dataset/swap.rs	Builds swap dataset layout with routing-option band dimension and updates related tests.
crates/revrt/src/dataset/reader.rs	Renames reader and makes derived reads option-aware; adds cell-cost accessor and tests.
crates/revrt/src/dataset/mod.rs	Threads option count through swap init; adds source-cell reading for driver rules.
crates/revrt/src/dataset/derived.rs	Materializes derived data per band chunk; updates chunk bookkeeping and tests.
crates/revrt/src/cost/mod.rs	Refactors cost function to parse via new input schema and apply per-option selection.
crates/revrt/src/cost/inputs.rs	New: schema parsing/validation for routing_options, drivers, and transition_costs.
crates/revrt/src/cost/components.rs	New: shared cost-function component types (layers, barriers, drivers, transition costs).
crates/revrt/src/benchmark.rs	Updates benchmark cost JSON to new routing_options.default schema.
crates/revrt/benches/standard.rs	Updates benchmarks to use new index constructor.
crates/cli/src/main.rs	Updates CLI binary to use new index constructor.
Cargo.toml	Enables serde_json preserve_order to keep routing option ordering stable.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.63%. Comparing base (f9ec058) to head (6b0196b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #281   +/-   ##
=======================================
  Coverage   96.63%   96.63%           
=======================================
  Files          27       27           
  Lines        3237     3240    +3     
  Branches      391      391           
=======================================
+ Hits         3128     3131    +3     
  Misses         61       61           
  Partials       48       48           

Flag	Coverage Δ
unittests	96.63% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ppinchuk]

Will fix windows rust checks in upcoming PR (withtin the hour)