cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo

Depth to Z fusion algorithms.

Attributes

_NEIGHBOURS

_REQUIRED_SCALAR_LAYERS

Functions

has_required_bands(tile) → bool

Check required data fields for depth to Z fusion.

extract_scalar_layer(data_array) → numpy.ndarray | None

Extract a 2D scalar array from a 2D or 3D xarray layer.

build_masks(depth, z_map, tile_id[, invalidity]) → tuple[numpy.ndarray, numpy.ndarray]

Build domain and anchor masks.

_slices(height, width, delta_i, delta_j)

Slice pairs for a pixel and its neighbour.

estimate_global_sigma(depth, valid) → float

Estimate a robust global sigma from the depth IQR.

auto_sigma_per_tile(depth, tile_id, valid) → dict

Estimate one depth-difference sigma per tile.

build_edge_weights(depth, tile_id, valid, sigma_d, ...) → dict[tuple[int, int], numpy.ndarray]

Compute per-direction depth-guided edge weights.

_slope_from_pairs(delta_depth, delta_z, min_pairs) → float | None

Through-origin depth->Z slope from neighbour differences, MAD-clipped

_anchor_pair_differences(depth, z_map, anchor_mask, ...) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Collect (dD, dZ, source tile id) over adjacent same-tile anchor pairs.

estimate_depth_to_z_scale(depth, z_map, anchor_mask, ...) → tuple[dict[float, float], float]

Estimate the signed depth->Z slope a in Z ~= a * depth + b per tile

center_depth_per_tile(depth, tile_id, anchor_mask, ...) → numpy.ndarray

Remove the arbitrary per-tile depth DC offset.

build_cross_tile_residual_targets(relief_map, tile_id, ...) → dict[tuple[int, int], numpy.ndarray]

Directed residual gradient targets that cancel the relief jump at borders.

build_slope_map(tile_id, scale_per_tile, global_slope) → numpy.ndarray

Expand the per-tile depth->Z slope into a per-pixel a map.

smooth_fill(values, known) → numpy.ndarray

Multiscale push-pull fill of a smooth scalar field over unknown pixels.

fuse_anisotropic(z_map, domain_mask, anchor_mask, ...) → tuple[numpy.ndarray, int, float]

Run Jacobi iterations for depth-guided anisotropic Z fusion.

mean_weight_map(edge_weights, domain_mask, tile_id) → numpy.ndarray

Compute per-pixel average edge weight from same-tile neighbors only.

update_depth_to_z_filling(dataset, fill_mask) → None

Merge depth-to-z provenance into EPI_FILLING in place.

fit_depth_to_z_tile(tile, lambda_data, depth_sigma, ...) → xarray.Dataset

Fit monocular depth structure onto the Z map of one point-cloud tile.

Module Contents

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo._NEIGHBOURS
cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo._REQUIRED_SCALAR_LAYERS
cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.has_required_bands(tile: xarray.Dataset) → bool[source]

Check required data fields for depth to Z fusion.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.extract_scalar_layer(data_array: xarray.DataArray) → numpy.ndarray | None[source]

Extract a 2D scalar array from a 2D or 3D xarray layer.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.build_masks(depth: numpy.ndarray, z_map: numpy.ndarray, tile_id: numpy.ndarray, invalidity: numpy.ndarray | None = None) → tuple[numpy.ndarray, numpy.ndarray][source]

Build domain and anchor masks.

Domain mask: where depth is defined and tile id is defined with a valid non-nodata value. Anchor mask: subset of domain where Z is defined and not flagged as invalid by the outlier removal step.

Outlier removal does not NaN-fill Z; instead it sets band values in EPI_INVALIDITY_MASK to 1. Without checking this mask, removed pixels (which carry an interpolated, unreliable Z) would be included as stereo data-attachment anchors, polluting the Jacobi solve.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo._slices(height: int, width: int, delta_i: int, delta_j: int)[source]

Slice pairs for a pixel and its neighbour.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.estimate_global_sigma(depth: numpy.ndarray, valid: numpy.ndarray) → float[source]

Estimate a robust global sigma from the depth IQR.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.auto_sigma_per_tile(depth: numpy.ndarray, tile_id: numpy.ndarray, valid: numpy.ndarray) → dict[source]

Estimate one depth-difference sigma per tile.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.build_edge_weights(depth: numpy.ndarray, tile_id: numpy.ndarray, valid: numpy.ndarray, sigma_d: float | dict, cross_tile_weight: float) → dict[tuple[int, int], numpy.ndarray][source]

Compute per-direction depth-guided edge weights.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo._slope_from_pairs(delta_depth: numpy.ndarray, delta_z: numpy.ndarray, min_pairs: int) → float | None[source]

Through-origin depth->Z slope from neighbour differences, MAD-clipped

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo._anchor_pair_differences(depth: numpy.ndarray, z_map: numpy.ndarray, anchor_mask: numpy.ndarray, tile_id: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Collect (dD, dZ, source tile id) over adjacent same-tile anchor pairs.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.estimate_depth_to_z_scale(depth: numpy.ndarray, z_map: numpy.ndarray, anchor_mask: numpy.ndarray, tile_id: numpy.ndarray, min_pairs: int = 64, min_spread_ratio: float = 0.25, max_slope_ratio: float = 3.0) → tuple[dict[float, float], float][source]

Estimate the signed depth->Z slope a in Z ~= a * depth + b per tile Returns a {tile_id: a} dict plus the robust global slope fallback

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.center_depth_per_tile(depth: numpy.ndarray, tile_id: numpy.ndarray, anchor_mask: numpy.ndarray, domain_mask: numpy.ndarray) → numpy.ndarray[source]

Remove the arbitrary per-tile depth DC offset.

Each monocular tile_id carries its own absolute depth level, which is meaningless across tiles. Multiplying the raw depth by the slope therefore injects a huge relief jump at every tile boundary; inside a hole (no anchors to absorb it) that jump surfaces as a sharp Z artefact. Subtracting a per-tile reference depth keeps only the within-tile relief, so the relief is continuous across boundaries and the smooth residual carries the true level.

The reference is the anchor mean where available (so relief is ~zero-mean where Z is known), falling back to the domain mean, then to zero.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.build_cross_tile_residual_targets(relief_map: numpy.ndarray, tile_id: numpy.ndarray, domain_mask: numpy.ndarray) → dict[tuple[int, int], numpy.ndarray][source]

Directed residual gradient targets that cancel the relief jump at borders.

The analytic relief is continuous within a tile but jumps across tile boundaries (different slope and centered-depth level on each side). Because the residual solve is dominated by smoothness (neighbour weights typically outweigh the per-anchor data term), the residual stays smooth across the border while the relief jumps, so fused = relief + residual inherits most of that jump – even at anchored borders where both sides carry a valid Z.

For the residual solve we therefore request, on every cross-tile edge, a residual gradient b_ij = relief_j - relief_i. This makes the smoothness term prefer a zero fused gradient (continuity) across the border instead of the spurious relief jump. The data term still pulls each anchored side toward its true Z, so the genuine (small) terrain step across the border is preserved while the large relief artefact is removed. Intra-tile edges keep a zero target (unchanged harmonic behaviour).

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.build_slope_map(tile_id: numpy.ndarray, scale_per_tile: dict[float, float], global_slope: float) → numpy.ndarray[source]

Expand the per-tile depth->Z slope into a per-pixel a map.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.smooth_fill(values: numpy.ndarray, known: numpy.ndarray) → numpy.ndarray[source]

Multiscale push-pull fill of a smooth scalar field over unknown pixels.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.fuse_anisotropic(z_map: numpy.ndarray, domain_mask: numpy.ndarray, anchor_mask: numpy.ndarray, lambda_data: float, edge_weights: dict[tuple[int, int], numpy.ndarray], iterations: int, tol: float, init: numpy.ndarray | None = None, edge_targets: dict[tuple[int, int], numpy.ndarray] | None = None) → tuple[numpy.ndarray, int, float][source]

Run Jacobi iterations for depth-guided anisotropic Z fusion.

edge_targets optionally provides a directed gradient target b_ij per edge (the desired fused_i - fused_j). With it the smoothness energy becomes w_ij (fused_i - fused_j - b_ij)**2, letting the solve reproduce a prescribed jump on selected edges (used to cancel the relief discontinuity across tile borders). When None the classic harmonic target (0) is used

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.mean_weight_map(edge_weights: dict[tuple[int, int], numpy.ndarray], domain_mask: numpy.ndarray, tile_id: numpy.ndarray) → numpy.ndarray[source]

Compute per-pixel average edge weight from same-tile neighbors only.

Cross-tile links are excluded from this diagnostic map to avoid imprinting the tile grid (which can create regular square-like artifacts when cross_tile_weight is small or zero).

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.update_depth_to_z_filling(dataset: xarray.Dataset, fill_mask: numpy.ndarray) → None[source]

Merge depth-to-z provenance into EPI_FILLING in place.

If EPI_FILLING already exists, update the “depth_to_z” band or append it. Otherwise, create EPI_FILLING with a single “depth_to_z” band.

cars.applications.depth_to_z_fusion.depth_to_z_fusion_algo.fit_depth_to_z_tile(tile: xarray.Dataset, lambda_data: float, depth_sigma: float | None, depth_sigma_auto: bool, detail_scale: float, cross_tile_weight: float, fill_values: str | None, iterations: int, tol: float) → xarray.Dataset[source]

Fit monocular depth structure onto the Z map of one point-cloud tile.