xpark.dataset.ImageExtractDepth#

class xpark.dataset.ImageExtractDepth(_local_model: str = 'depth-anything/DA3MONO-LARGE', *, model_kind: Literal['mono', 'metric', 'anyview'] = 'mono', focal: float | None = None, max_resolution: int = 504, resize_method: Literal['upper_bound_resize', 'lower_bound_resize'] = 'upper_bound_resize', precision: Literal['auto', 'bf16', 'fp16', 'fp32'] = 'auto')#

Single-view depth extraction processor: one image -> one depth map.

Each input row is one image and produces an HxW float32 depth map (H / W are the processing-resolution height / width max_resolution, not upscaled to the input size). Images in a batch are independent samples with a single view: no cross-image attention and no silent cropping when aspect ratios differ.

Parameters:

  • _local_model – The DA3 model name for CPU or GPU, or BYO weights. A name must be one of the registry keys below; anything path-shaped – an absolute local directory or an fsspec URI (cos:// / s3:// / file://) – is loaded as user weights. The caller is responsible for what it points at: only the registered models are vetted by xpark. default model is “depth-anything/DA3MONO-LARGE” available models: [‘depth-anything/DA3MONO-LARGE’, ‘depth-anything/DA3METRIC-LARGE’, ‘depth-anything/DA3-SMALL’, ‘depth-anything/DA3-BASE’]

  • focal – Pixel focal length for DA3METRIC-LARGE metric conversion (mean of fx/fy of the calibration matrix K). Required for the metric model; ignored otherwise.

  • model_kind – Model family. "mono" = relative monocular depth, "metric" = metric depth (needs focal), "anyview" = multi-view ray geometry (delegates to ImageExtractRay). It selects the preprocessing/postprocessing branch, and for a registered model it must agree with the registry entry. BYO weights have no registry entry, so they run exactly as specified here. Defaults to "mono", matching the default model.

  • max_resolution – Maximum processing resolution (longest side). Lower it for more throughput, higher for more detail. Defaults to 504.

  • resize_method – Resize strategy, “upper_bound_resize” or “lower_bound_resize”. Defaults to "upper_bound_resize".

  • precision – Inference precision. "auto" = BF16 > FP16 on GPU, FP32 on CPU. Explicit "bf16" / "fp16" / "fp32" force a strategy. Defaults to "auto".

Raises:

ValueError – If _local_model is neither a registered model nor an absolute BYO location, if model_kind is not one of "mono" / "metric" / "anyview" or contradicts the model’s registered family, or if a metric model is used without focal.

Note

Passing an any-view model name – or BYO weights whose model_kind selects the any-view family – delegates the whole inference to ImageExtractRay – each image runs as a single-view scene and this operator returns the depth component of its ray_map. Only the mono / metric models run the shared single-view path.

Confidence maps are not part of this operator’s output. To obtain the per-pixel conf in [0, 1] for single images, use ImageExtractRay with each image wrapped as a single-view sequence; the confidence semantics are identical across operators.

NOTE: needs the ai-git extra (pip install "xpark[ai-git]") — the DA3 package is installed from a git ref, not from PyPI (see pyproject.toml). Missing it raises ImportError when the weights are loaded.

Examples

from xpark.dataset import ImageExtractDepth, from_items
from xpark.dataset.expressions import col

ds = from_items([{"image": "bottle_front.jpg"}])
ds = ds.with_column(
    "depth",
    ImageExtractDepth().options(num_workers={"GPU": 1}, batch_size=8).with_column(col("image")),
)
print(ds.take(1))

Methods

__call__(images)

Call self as a function.

options(**kwargs)

with_column(images)

__call__(images: pa.ChunkedArray) → pa.Array#

Call self as a function.

options(**kwargs: Unpack[ExprUDFOptions]) → Self#
with_column(images: pa.ChunkedArray) → pa.Array#