API Reference¶

Find a path between two points on the crop using configured solver backend.

Load a DSM tile for the given lat/lon coordinates.

Load a (2*half_tiles+1) x (2*half_tiles+1) grid of tiles centered on the given coordinates.

Handles latitude bounds by substituting flat tiles for out-of-bounds rows. Handles longitude wrapping at -180/180.

Compute how many tiles are concatenated to produce a crop for the given resolution.

Example: for small resolutions half_tiles==1 -> N=3 -> total_tiles=9

Generate a single dataset sample.

Count consecutive valid samples starting from index 0.

A sample is valid if it has all required files under the expected split/lat/lon subdirectories: - {split}/tensors/{lat}/{lon}/{index:010d}.npy.zst - {split}/metadata/{lat}/{lon}/{index:010d}.yaml - {split}/images/{solver}/{lat}/{lon}/{index:010d}.png for preview-subset rows when images are enabled

Stops counting at the first incomplete sample and deletes any partial files.

Main orchestration function for generating dataset samples.

Return an exact optimum, proved no_path, or an explicitly censored solve.

Invalid inputs or float64 cost overflow raise ValueError. Blocked endpoints yield proved no_path; arithmetic failure never proves infeasibility. Zero budget censors a distinct-endpoint request. Budgets count expanded outgoing neighborhoods; settling a goal does not spend an expansion. JIT compilation is included in elapsed_seconds on the first invocation.

Return whether the reference graph has any route from start to goal.

The edge set is the one solve_reference searches: eight neighbours, obstacles checked at the destination cell only, every other edge finite. Reachability therefore needs no terrain, and False is exactly the case the solver would prove no_path. Blocked endpoints are disconnected.

Dijkstra on transposed edges computes directed original costs to goal.

Relaxing predecessor u from current v adds w(u,v), never w(v,u). Only proved/settled costs are published; targets are evaluator-only. Float64 cost overflow raises ValueError instead of publishing a field.

Re-cost legal integer 8-connected paths; return NaN for illegal routes.

Validate/decode ordinary tensor inputs independently of stored route labels.

Build a directed graph from a 2D elevation array for pathfinding.

Each pixel becomes a node with coordinates (i, j). Edges connect to neighboring pixels with weights based on physical distance and elevation cost.

where distance_m is 30m for cardinal directions, 30*sqrt(2) for diagonals.

Check if a path crosses any obstacles in the provided mask.

Return a boolean mask of a rotated superellipse.

Sample superellipse exponent n from configuration.

Supports the following distribution types in obstacles_cfg['shape']['n']['distribution']: - 'uniform' : uniform between n_min and n_max - 'log_uniform' : uniform in log-space between n_min and n_max - 'beta' : beta distribution (a,b) scaled to [n_min, n_max]

If the nested shape.n structure is missing, the function reads obstacles_cfg['n_min'], obstacles_cfg['n_max'], and obstacles_cfg['n_distribution'].

Return an angle in radians uniformly sampled from [0, 2*pi).

Angles are not configurable; they are always sampled uniformly in radians.

Serialize calibration checks, source scans, and publication per output directory.

A complete receipt is replaced only by explicit resume=False, overwrite=True. Every complete version remains available by receipt hash.

Download an archive with bounded retries and a hashed completion receipt.

extracted means every DSM member passed CRC/size verification and was published atomically as an individual file. Failures and HTTP absence remain distinct in the archive receipt; the function returns five fields.

Generate a PNG visualization of URL status.

Download the world grid or explicitly refresh selected 5-degree archives.

Resume validates hashed receipts. CSV records without a hashed receipt remain legacy_unverified without being redownloaded automatically. Explicit archive_pairs retries only those archives, preserving other records and tiles. Use resume=False to force refresh even verified archives. Unverified or failed records never count as complete coverage.

Parse a path .csv file with rows "row,col" (no header) and return [[row, col], ...].

Generate Parquet shards for the selected resolutions.

Prepare the export directory for upload.

Idempotent by default: each step inspects the current export directory and skips work that already produced its expected artifact. Use ExportSteps.force_* flags (or the master force_all) to redo a specific step. Notebook execution covers all four templates at each selected resolution. Outputs are reused only when their input/source/config identities and execution evidence match.

keep_existing_configs also retains compatible declarations from the existing root README. Retain that card only after verifying earlier remote uploads; this option does not contact the repository or verify that those Parquets exist remotely.

Upload the prepared export tree to Hugging Face.

Encode a numpy array as zstd-compressed raw bytes.

Decode a zstd-compressed tensor blob back to numpy array.

Save a numpy tensor to a compressed file.

Load a tensor from a compressed file.

Convert HWC elevation/markers[/obstacles] to an HWC uint8 BGR preview.

Both route arguments contain ordered integer (row, column) vertices; the first is blue and the alternative orange, with white halos. Coordinates must be finite integers within the raster. Invalid geometry raises instead of being clipped. This is a display validation, not a route legality check.

Elevation uses the shared sage–sand scale; elev_range is expressed in the same units as channel zero. Unlabelled raster previews may use normalized elevation. For labelled metre plots, use passage.plotting.decode_scene. Obstacles are charcoal with light hatching. White circles/stars mark start and goal, above all paths. The call signature and BGR output are preserved.