depth-estimation 0.0.6__tar.gz → 0.0.8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. depth_estimation-0.0.8/PKG-INFO +365 -0
  2. depth_estimation-0.0.8/README.md +313 -0
  3. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/pyproject.toml +8 -2
  4. depth_estimation-0.0.8/src/depth_estimation/__init__.py +70 -0
  5. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/cli.py +221 -11
  6. depth_estimation-0.0.8/src/depth_estimation/data/__init__.py +124 -0
  7. depth_estimation-0.0.8/src/depth_estimation/data/base_dataset.py +81 -0
  8. depth_estimation-0.0.8/src/depth_estimation/data/diode.py +203 -0
  9. depth_estimation-0.0.8/src/depth_estimation/data/folder.py +161 -0
  10. depth_estimation-0.0.8/src/depth_estimation/data/hub.py +84 -0
  11. depth_estimation-0.0.8/src/depth_estimation/data/kitti.py +221 -0
  12. depth_estimation-0.0.8/src/depth_estimation/data/nyu_depth_v2.py +174 -0
  13. depth_estimation-0.0.8/src/depth_estimation/evaluation/__init__.py +56 -0
  14. depth_estimation-0.0.8/src/depth_estimation/evaluation/evaluate.py +408 -0
  15. depth_estimation-0.0.8/src/depth_estimation/evaluation/metrics.py +282 -0
  16. depth_estimation-0.0.8/src/depth_estimation/evaluation/profiling.py +143 -0
  17. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/auto/processing_auto.py +2 -2
  18. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v1/__init__.py +15 -2
  19. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v2/__init__.py +15 -2
  20. depth_estimation-0.0.8/src/depth_estimation/models/depth_anything_v3/__init__.py +50 -0
  21. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_pro/__init__.py +15 -2
  22. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/marigold_dc/__init__.py +15 -2
  23. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/midas/__init__.py +15 -2
  24. depth_estimation-0.0.8/src/depth_estimation/models/moge/__init__.py +27 -0
  25. depth_estimation-0.0.8/src/depth_estimation/models/moge/configuration_moge.py +98 -0
  26. depth_estimation-0.0.8/src/depth_estimation/models/moge/modeling_moge.py +1503 -0
  27. depth_estimation-0.0.8/src/depth_estimation/models/omnivggt/__init__.py +27 -0
  28. depth_estimation-0.0.8/src/depth_estimation/models/omnivggt/configuration_omnivggt.py +62 -0
  29. depth_estimation-0.0.8/src/depth_estimation/models/omnivggt/modeling_omnivggt.py +1357 -0
  30. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/pixel_perfect_depth/__init__.py +15 -2
  31. depth_estimation-0.0.8/src/depth_estimation/models/vggt/__init__.py +27 -0
  32. depth_estimation-0.0.8/src/depth_estimation/models/vggt/configuration_vggt.py +71 -0
  33. depth_estimation-0.0.8/src/depth_estimation/models/vggt/modeling_vggt.py +1133 -0
  34. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/zoedepth/__init__.py +15 -2
  35. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/registry.py +6 -1
  36. depth_estimation-0.0.8/src/depth_estimation.egg-info/PKG-INFO +365 -0
  37. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation.egg-info/SOURCES.txt +22 -0
  38. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation.egg-info/requires.txt +7 -1
  39. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/tests/test_auto.py +30 -11
  40. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/tests/test_config.py +100 -0
  41. depth_estimation-0.0.8/tests/test_data.py +289 -0
  42. depth_estimation-0.0.8/tests/test_evaluation.py +290 -0
  43. depth_estimation-0.0.6/PKG-INFO +0 -197
  44. depth_estimation-0.0.6/README.md +0 -150
  45. depth_estimation-0.0.6/src/depth_estimation/__init__.py +0 -40
  46. depth_estimation-0.0.6/src/depth_estimation/models/depth_anything_v3/__init__.py +0 -29
  47. depth_estimation-0.0.6/src/depth_estimation.egg-info/PKG-INFO +0 -197
  48. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/LICENSE +0 -0
  49. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/setup.cfg +0 -0
  50. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/configuration_utils.py +0 -0
  51. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/modeling_utils.py +0 -0
  52. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/__init__.py +0 -0
  53. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/auto/__init__.py +0 -0
  54. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/auto/modeling_auto.py +0 -0
  55. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v1/configuration_depth_anything_v1.py +0 -0
  56. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v1/modeling_depth_anything_v1.py +0 -0
  57. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v2/configuration_depth_anything_v2.py +0 -0
  58. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v2/modeling_depth_anything_v2.py +0 -0
  59. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v3/configuration_depth_anything_v3.py +0 -0
  60. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_anything_v3/modeling_depth_anything_v3.py +0 -0
  61. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_pro/configuration_depth_pro.py +0 -0
  62. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/depth_pro/modeling_depth_pro.py +0 -0
  63. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/marigold_dc/configuration_marigold_dc.py +0 -0
  64. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/marigold_dc/modeling_marigold_dc.py +0 -0
  65. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/midas/configuration_midas.py +0 -0
  66. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/midas/modeling_midas.py +0 -0
  67. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/pixel_perfect_depth/configuration_ppd.py +0 -0
  68. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/pixel_perfect_depth/modeling_ppd.py +0 -0
  69. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/zoedepth/configuration_zoedepth.py +0 -0
  70. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/models/zoedepth/modeling_zoedepth.py +0 -0
  71. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/output.py +0 -0
  72. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/pipeline_utils.py +0 -0
  73. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/pipelines/__init__.py +0 -0
  74. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/pipelines/depth_estimation.py +0 -0
  75. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation/processing_utils.py +0 -0
  76. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation.egg-info/dependency_links.txt +0 -0
  77. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation.egg-info/entry_points.txt +0 -0
  78. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/src/depth_estimation.egg-info/top_level.txt +0 -0
  79. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/tests/test_model.py +0 -0
  80. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/tests/test_pipeline.py +0 -0
  81. {depth_estimation-0.0.6 → depth_estimation-0.0.8}/tests/test_processor.py +0 -0
@@ -0,0 +1,365 @@
1
+ Metadata-Version: 2.4
2
+ Name: depth_estimation
3
+ Version: 0.0.8
4
+ Summary: A Transformers-style Python library for monocular depth estimation
5
+ Author: shriarul5273
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/shriarul5273/depth_estimation
8
+ Project-URL: Repository, https://github.com/shriarul5273/depth_estimation
9
+ Project-URL: Issues, https://github.com/shriarul5273/depth_estimation/issues
10
+ Keywords: depth-estimation,monocular-depth,computer-vision,deep-learning,pytorch
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.9
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Classifier: Topic :: Scientific/Engineering :: Image Recognition
19
+ Classifier: Intended Audience :: Developers
20
+ Classifier: Intended Audience :: Science/Research
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: torch==2.10.0
25
+ Requires-Dist: torchvision>=0.15
26
+ Requires-Dist: Pillow>=9.0
27
+ Requires-Dist: numpy>=1.24
28
+ Requires-Dist: matplotlib>=3.6
29
+ Requires-Dist: opencv-python>=4.8
30
+ Requires-Dist: huggingface-hub>=0.16
31
+ Requires-Dist: transformers
32
+ Requires-Dist: diffusers
33
+ Requires-Dist: accelerate
34
+ Requires-Dist: timm>=0.9.1
35
+ Requires-Dist: einops>=0.6
36
+ Requires-Dist: addict
37
+ Requires-Dist: h5py
38
+ Requires-Dist: tqdm
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest>=7.0; extra == "dev"
41
+ Requires-Dist: pytest-cov; extra == "dev"
42
+ Provides-Extra: transformers
43
+ Requires-Dist: transformers>=4.30; extra == "transformers"
44
+ Provides-Extra: diffusers
45
+ Requires-Dist: diffusers>=0.25; extra == "diffusers"
46
+ Provides-Extra: data
47
+ Requires-Dist: h5py>=3.0; extra == "data"
48
+ Requires-Dist: tqdm; extra == "data"
49
+ Provides-Extra: all
50
+ Requires-Dist: depth_estimation[data,diffusers,transformers]; extra == "all"
51
+ Dynamic: license-file
52
+
53
+ # depth_estimation
54
+
55
+ A **Python library** for monocular depth estimation.
56
+
57
+ Provides a unified, modular API for inference, evaluation, and dataset loading — supporting **12 model families** with **28 variants** and designed to accommodate new models with minimal friction.
58
+
59
+ ## Installation
60
+
61
+ ```bash
62
+ pip install depth-estimation
63
+ ```
64
+
65
+ For dataset downloading (NYU Depth V2) install the `data` extra:
66
+
67
+ ```bash
68
+ pip install "depth-estimation[data]" # adds h5py, tqdm
69
+ ```
70
+
71
+ For a full list of dependencies see [docs/dependencies.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/dependencies.md).
72
+
73
+ ---
74
+
75
+ ## Quick Start
76
+
77
+ | | Pipeline API | Auto Classes |
78
+ |---|---|---|
79
+ | **Setup** | One call, model + processor bundled | Load model and processor separately |
80
+ | **Inference** | Pass image path directly | Call `processor()`, `model()`, `postprocess()` manually |
81
+ | **Control** | Low — handles everything for you | High — you control each step |
82
+ | **Output** | `DepthOutput` with `.depth`, `.colored_depth`, `.metadata` | Raw depth tensor |
83
+ | **Best for** | Quick inference, scripts, demos | Custom pipelines, research, fine-grained control |
84
+
85
+ ### Pipeline API (Recommended)
86
+
87
+ ```python
88
+ from depth_estimation import pipeline
89
+
90
+ pipe = pipeline("depth-estimation", model="depth-anything-v2-vitb")
91
+ result = pipe("image.jpg")
92
+
93
+ depth_map = result.depth # np.ndarray, float32, (H, W)
94
+ colored = result.colored_depth # np.ndarray, uint8, (H, W, 3)
95
+ meta = result.metadata # dict with model info
96
+ ```
97
+
98
+ ### Auto Classes
99
+
100
+ ```python
101
+ from depth_estimation import AutoDepthModel, AutoProcessor
102
+ import torch
103
+
104
+ model = AutoDepthModel.from_pretrained("zoedepth")
105
+ processor = AutoProcessor.from_pretrained("zoedepth")
106
+
107
+ inputs = processor("image.jpg")
108
+ with torch.no_grad():
109
+ depth = model(inputs["pixel_values"])
110
+
111
+ result = processor.postprocess(depth, inputs["original_sizes"])
112
+ ```
113
+
114
+ ### Batch Inference
115
+
116
+ ```python
117
+ results = pipe(["img1.jpg", "img2.jpg", "img3.jpg"], batch_size=2)
118
+ for r in results:
119
+ print(r.depth.shape)
120
+ ```
121
+
122
+ ---
123
+
124
+ ## Supported Models
125
+
126
+ 12 model families · 28 variants — see [docs/models.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/models.md) for the full list.
127
+
128
+ | Family | Variants | Depth type |
129
+ |---|---|---|
130
+ | Depth Anything v1 | vits / vitb / vitl | Relative |
131
+ | Depth Anything v2 | vits / vitb / vitl | Relative |
132
+ | Depth Anything v3 | small / base / large / giant + nested + metric + mono | Relative + Metric |
133
+ | ZoeDepth | nyu-kitti | Metric |
134
+ | MiDaS | dpt-large / dpt-hybrid / beit-large | Relative |
135
+ | Apple DepthPro | — | Metric |
136
+ | Pixel-Perfect Depth | — | Relative |
137
+ | Marigold-DC | — | Relative (depth completion) |
138
+ | MoGe | v1 vitl / v2 vitl / v2 vitb / v2 vits (+ normal variants) | Metric |
139
+ | OmniVGGT | vitl | Metric |
140
+ | VGGT | standard / commercial | Metric |
141
+
142
+ ---
143
+
144
+ ## Datasets
145
+
146
+ `load_dataset()` downloads and loads standard depth benchmarks with a single call.
147
+
148
+ ```python
149
+ from depth_estimation import load_dataset
150
+
151
+ # NYU Depth V2 — auto-downloads ~2.8 GB on first use
152
+ ds = load_dataset("nyu_depth_v2", split="test")
153
+
154
+ # DIODE val set — auto-downloads ~2.6 GB on first use
155
+ ds = load_dataset("diode", split="val", scene_type="indoors")
156
+
157
+ # KITTI Eigen — path required (see docs/data.md for download instructions)
158
+ ds = load_dataset("kitti_eigen", split="test", root="/data/kitti")
159
+
160
+ # Generic RGB + depth folder
161
+ ds = load_dataset("folder", image_dir="rgb/", depth_dir="depth/")
162
+ ```
163
+
164
+ Every dataset returns the same schema, compatible with `torch.utils.data.DataLoader`:
165
+
166
+ ```python
167
+ sample = ds[0]
168
+ sample["pixel_values"] # (3, H, W) float32, normalised [0, 1]
169
+ sample["depth_map"] # (1, H, W) float32, metres
170
+ sample["valid_mask"] # (1, H, W) bool
171
+ ```
172
+
173
+ | Dataset | Auto-download | GT type | Test size |
174
+ |---|---|---|---|
175
+ | `nyu_depth_v2` | Yes (~2.8 GB) | Dense, metric | 654 images |
176
+ | `diode` | Yes (~2.6 GB val) | Dense, metric | 771 images |
177
+ | `kitti_eigen` | No (registration required) | Sparse LiDAR | 697 images |
178
+ | `folder` | N/A | Any | N/A |
179
+
180
+ See [docs/data.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/data.md) for full documentation.
181
+
182
+ ---
183
+
184
+ ## Evaluation
185
+
186
+ Evaluate any model on any supported dataset with a single call. Relative-depth models are aligned per-sample (least-squares scale + shift) before metric computation — detected automatically from `config.is_metric`.
187
+
188
+ ### Evaluate one model
189
+
190
+ ```python
191
+ from depth_estimation.evaluation import evaluate
192
+
193
+ results = evaluate("depth-anything-v2-vitb", "nyu_depth_v2", split="test")
194
+ # {"abs_rel": 0.043, "sq_rel": 0.012, "rmse": 0.312,
195
+ # "rmse_log": 0.061, "delta1": 0.982, "delta2": 0.997,
196
+ # "delta3": 0.999, "n_samples": 654}
197
+ ```
198
+
199
+ ### Compare multiple models
200
+
201
+ ```python
202
+ from depth_estimation.evaluation import compare
203
+
204
+ compare(
205
+ ["depth-anything-v2-vits", "depth-anything-v2-vitb", "depth-anything-v2-vitl"],
206
+ dataset="nyu_depth_v2",
207
+ )
208
+ ```
209
+
210
+ Prints a formatted table with best values marked (`*`).
211
+
212
+ ### Compute metrics on custom predictions
213
+
214
+ ```python
215
+ from depth_estimation.evaluation import DepthMetrics, Evaluator
216
+
217
+ # Per-prediction
218
+ metrics = DepthMetrics()
219
+ result = metrics(pred_tensor, gt_tensor, valid_mask)
220
+
221
+ # Accumulate correctly across batches (proper RMSE, not mean-of-means)
222
+ ev = Evaluator()
223
+ for pred, gt, mask in dataloader:
224
+ ev.update(pred, gt, mask)
225
+ final = ev.compute()
226
+ ```
227
+
228
+ ### Profile latency
229
+
230
+ ```python
231
+ from depth_estimation.evaluation import profile_latency
232
+
233
+ p = profile_latency("depth-anything-v2-vitb", num_runs=100)
234
+ print(f"{p['mean_ms']:.1f} ms | {p['fps']:.1f} FPS | {p['memory_mb']:.0f} MiB")
235
+ ```
236
+
237
+ Metrics: `abs_rel`, `sq_rel`, `rmse`, `rmse_log`, `delta1` / `delta2` / `delta3`.
238
+
239
+ See [docs/evaluation.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/evaluation.md) for full documentation.
240
+
241
+ ### Evaluation scripts
242
+
243
+ Ready-to-run scripts are in `examples/`:
244
+
245
+ ```bash
246
+ # NYU Depth V2 (auto-downloads dataset)
247
+ python examples/eval_nyu.py --model depth-anything-v2-vitb
248
+ python examples/eval_nyu.py --compare # all models, comparison table
249
+
250
+ # KITTI Eigen (manual download required)
251
+ python examples/eval_kitti.py --model zoedepth --dataset-root /data/kitti
252
+
253
+ # DIODE (auto-downloads ~2.6 GB val set)
254
+ python examples/eval_diode.py --scene-type indoors
255
+
256
+ # Quick 50-sample sanity check on any script
257
+ python examples/eval_nyu.py --model depth-anything-v2-vits --num-samples 50
258
+
259
+ # Save results to JSON
260
+ python examples/eval_nyu.py --model depth-pro --output results/depth_pro_nyu.json
261
+ ```
262
+
263
+ ---
264
+
265
+ ## CLI
266
+
267
+ After installing the package, a `depth-estimate` command is available.
268
+
269
+ ```bash
270
+ # Single image → saves demo_depth.png
271
+ depth-estimate predict examples/demo.png --model depth-anything-v2-vitb
272
+
273
+ # Batch (directory or glob) → saves to results/
274
+ depth-estimate predict "images/*.jpg" --model depth-anything-v2-vitb --output-dir results/
275
+
276
+ # Video → saves side-by-side RGB | depth as MP4
277
+ depth-estimate predict video.mp4 --model depth-anything-v2-vitb --output depth_video.mp4
278
+
279
+ # Save raw float32 array (.npy) alongside the PNG
280
+ depth-estimate predict examples/demo.png --model depth-anything-v2-vitb --format both
281
+
282
+ # Change colormap
283
+ depth-estimate predict examples/demo.png --model depth-anything-v2-vitb --colormap inferno
284
+
285
+ # List all available models
286
+ depth-estimate list-models
287
+
288
+ # Show config details for a model
289
+ depth-estimate info depth-anything-v2-vitb
290
+
291
+ # Evaluate a model on NYU Depth V2 (auto-downloads ~2.8 GB)
292
+ depth-estimate evaluate --model depth-anything-v2-vitb --dataset nyu_depth_v2
293
+
294
+ # Quick 50-sample check
295
+ depth-estimate evaluate --model depth-pro --dataset nyu --num-samples 50
296
+
297
+ # Compare multiple models and save results
298
+ depth-estimate evaluate --compare --dataset nyu_depth_v2 --output results.json
299
+ ```
300
+
301
+ **Global flags** (`--device`, `--quiet`, `--verbose`) go before the subcommand:
302
+
303
+ ```bash
304
+ depth-estimate --device cpu --quiet predict examples/demo.png --model depth-anything-v2-vitb
305
+ ```
306
+
307
+ All subcommands support `--json` for machine-readable output. See [docs/cli.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/cli.md) for full documentation.
308
+
309
+ ---
310
+
311
+ ## Architecture
312
+
313
+ The library follows the **HuggingFace Transformers** modular design philosophy:
314
+
315
+ - **Single model, single file** — each model's architecture is self-contained
316
+ - **Shared processor** — preprocessing/postprocessing is not duplicated
317
+ - **Registry-based auto-loading** — new models self-register, no core changes needed
318
+ - **Config inheritance** — configs override only what differs from the base
319
+
320
+ ```
321
+ Input → Processor.preprocess() → Model.forward() → Processor.postprocess() → DepthOutput
322
+ ```
323
+
324
+ ## Adding a New Model
325
+
326
+ 1. Create `src/depth_estimation/models/your_model/`
327
+ 2. Add `configuration_your_model.py` (inherit `BaseDepthConfig`)
328
+ 3. Add `modeling_your_model.py` (inherit `BaseDepthModel`, single file)
329
+ 4. Add `__init__.py` with `MODEL_REGISTRY.register(...)`
330
+
331
+ That's it — `AutoDepthModel`, `AutoProcessor`, and `pipeline()` will automatically resolve your model. See [docs/adding_a_model.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/adding_a_model.md) for a step-by-step guide.
332
+
333
+ ---
334
+
335
+ ## Running Tests
336
+
337
+ ```bash
338
+ pip install -e ".[dev]"
339
+ pytest tests/ -v
340
+ ```
341
+
342
+ ---
343
+
344
+ ## Acknowledgments
345
+
346
+ This library builds upon the incredible work of the following research teams:
347
+
348
+ | Model | Repository |
349
+ |---|---|
350
+ | **Depth Anything v1** | [github.com/LiheYoung/Depth-Anything](https://github.com/LiheYoung/Depth-Anything) |
351
+ | **Depth Anything v2** | [github.com/DepthAnything/Depth-Anything-V2](https://github.com/DepthAnything/Depth-Anything-V2) |
352
+ | **Depth Anything v3** | [github.com/DepthAnything/Depth-Anything-V3](https://github.com/DepthAnything/Depth-Anything-V3) |
353
+ | **DINOv2** | [github.com/facebookresearch/dinov2](https://github.com/facebookresearch/dinov2) |
354
+ | **DepthPro** | [github.com/apple/ml-depth-pro](https://github.com/apple/ml-depth-pro) |
355
+ | **ZoeDepth** | [github.com/isl-org/ZoeDepth](https://github.com/isl-org/ZoeDepth) |
356
+ | **MiDaS** | [github.com/isl-org/MiDaS](https://github.com/isl-org/MiDaS) |
357
+ | **Pixel-Perfect Depth** | [github.com/gangweix/Pixel-Perfect-Depth](https://github.com/gangweix/Pixel-Perfect-Depth) |
358
+ | **Marigold-DC** | [github.com/prs-eth/Marigold-DC](https://github.com/prs-eth/Marigold-DC) |
359
+ | **MoGe** | [github.com/microsoft/MoGe](https://github.com/microsoft/MoGe) |
360
+ | **VGGT** | [github.com/facebookresearch/vggt](https://github.com/facebookresearch/vggt) |
361
+ | **OmniVGGT** | [github.com/Livioni/OmniVGGT](https://github.com/Livioni/OmniVGGT) |
362
+
363
+ ## License
364
+
365
+ MIT
@@ -0,0 +1,313 @@
1
+ # depth_estimation
2
+
3
+ A **Python library** for monocular depth estimation.
4
+
5
+ Provides a unified, modular API for inference, evaluation, and dataset loading — supporting **12 model families** with **28 variants** and designed to accommodate new models with minimal friction.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ pip install depth-estimation
11
+ ```
12
+
13
+ For dataset downloading (NYU Depth V2) install the `data` extra:
14
+
15
+ ```bash
16
+ pip install "depth-estimation[data]" # adds h5py, tqdm
17
+ ```
18
+
19
+ For a full list of dependencies see [docs/dependencies.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/dependencies.md).
20
+
21
+ ---
22
+
23
+ ## Quick Start
24
+
25
+ | | Pipeline API | Auto Classes |
26
+ |---|---|---|
27
+ | **Setup** | One call, model + processor bundled | Load model and processor separately |
28
+ | **Inference** | Pass image path directly | Call `processor()`, `model()`, `postprocess()` manually |
29
+ | **Control** | Low — handles everything for you | High — you control each step |
30
+ | **Output** | `DepthOutput` with `.depth`, `.colored_depth`, `.metadata` | Raw depth tensor |
31
+ | **Best for** | Quick inference, scripts, demos | Custom pipelines, research, fine-grained control |
32
+
33
+ ### Pipeline API (Recommended)
34
+
35
+ ```python
36
+ from depth_estimation import pipeline
37
+
38
+ pipe = pipeline("depth-estimation", model="depth-anything-v2-vitb")
39
+ result = pipe("image.jpg")
40
+
41
+ depth_map = result.depth # np.ndarray, float32, (H, W)
42
+ colored = result.colored_depth # np.ndarray, uint8, (H, W, 3)
43
+ meta = result.metadata # dict with model info
44
+ ```
45
+
46
+ ### Auto Classes
47
+
48
+ ```python
49
+ from depth_estimation import AutoDepthModel, AutoProcessor
50
+ import torch
51
+
52
+ model = AutoDepthModel.from_pretrained("zoedepth")
53
+ processor = AutoProcessor.from_pretrained("zoedepth")
54
+
55
+ inputs = processor("image.jpg")
56
+ with torch.no_grad():
57
+ depth = model(inputs["pixel_values"])
58
+
59
+ result = processor.postprocess(depth, inputs["original_sizes"])
60
+ ```
61
+
62
+ ### Batch Inference
63
+
64
+ ```python
65
+ results = pipe(["img1.jpg", "img2.jpg", "img3.jpg"], batch_size=2)
66
+ for r in results:
67
+ print(r.depth.shape)
68
+ ```
69
+
70
+ ---
71
+
72
+ ## Supported Models
73
+
74
+ 12 model families · 28 variants — see [docs/models.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/models.md) for the full list.
75
+
76
+ | Family | Variants | Depth type |
77
+ |---|---|---|
78
+ | Depth Anything v1 | vits / vitb / vitl | Relative |
79
+ | Depth Anything v2 | vits / vitb / vitl | Relative |
80
+ | Depth Anything v3 | small / base / large / giant + nested + metric + mono | Relative + Metric |
81
+ | ZoeDepth | nyu-kitti | Metric |
82
+ | MiDaS | dpt-large / dpt-hybrid / beit-large | Relative |
83
+ | Apple DepthPro | — | Metric |
84
+ | Pixel-Perfect Depth | — | Relative |
85
+ | Marigold-DC | — | Relative (depth completion) |
86
+ | MoGe | v1 vitl / v2 vitl / v2 vitb / v2 vits (+ normal variants) | Metric |
87
+ | OmniVGGT | vitl | Metric |
88
+ | VGGT | standard / commercial | Metric |
89
+
90
+ ---
91
+
92
+ ## Datasets
93
+
94
+ `load_dataset()` downloads and loads standard depth benchmarks with a single call.
95
+
96
+ ```python
97
+ from depth_estimation import load_dataset
98
+
99
+ # NYU Depth V2 — auto-downloads ~2.8 GB on first use
100
+ ds = load_dataset("nyu_depth_v2", split="test")
101
+
102
+ # DIODE val set — auto-downloads ~2.6 GB on first use
103
+ ds = load_dataset("diode", split="val", scene_type="indoors")
104
+
105
+ # KITTI Eigen — path required (see docs/data.md for download instructions)
106
+ ds = load_dataset("kitti_eigen", split="test", root="/data/kitti")
107
+
108
+ # Generic RGB + depth folder
109
+ ds = load_dataset("folder", image_dir="rgb/", depth_dir="depth/")
110
+ ```
111
+
112
+ Every dataset returns the same schema, compatible with `torch.utils.data.DataLoader`:
113
+
114
+ ```python
115
+ sample = ds[0]
116
+ sample["pixel_values"] # (3, H, W) float32, normalised [0, 1]
117
+ sample["depth_map"] # (1, H, W) float32, metres
118
+ sample["valid_mask"] # (1, H, W) bool
119
+ ```
120
+
121
+ | Dataset | Auto-download | GT type | Test size |
122
+ |---|---|---|---|
123
+ | `nyu_depth_v2` | Yes (~2.8 GB) | Dense, metric | 654 images |
124
+ | `diode` | Yes (~2.6 GB val) | Dense, metric | 771 images |
125
+ | `kitti_eigen` | No (registration required) | Sparse LiDAR | 697 images |
126
+ | `folder` | N/A | Any | N/A |
127
+
128
+ See [docs/data.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/data.md) for full documentation.
129
+
130
+ ---
131
+
132
+ ## Evaluation
133
+
134
+ Evaluate any model on any supported dataset with a single call. Relative-depth models are aligned per-sample (least-squares scale + shift) before metric computation — detected automatically from `config.is_metric`.
135
+
136
+ ### Evaluate one model
137
+
138
+ ```python
139
+ from depth_estimation.evaluation import evaluate
140
+
141
+ results = evaluate("depth-anything-v2-vitb", "nyu_depth_v2", split="test")
142
+ # {"abs_rel": 0.043, "sq_rel": 0.012, "rmse": 0.312,
143
+ # "rmse_log": 0.061, "delta1": 0.982, "delta2": 0.997,
144
+ # "delta3": 0.999, "n_samples": 654}
145
+ ```
146
+
147
+ ### Compare multiple models
148
+
149
+ ```python
150
+ from depth_estimation.evaluation import compare
151
+
152
+ compare(
153
+ ["depth-anything-v2-vits", "depth-anything-v2-vitb", "depth-anything-v2-vitl"],
154
+ dataset="nyu_depth_v2",
155
+ )
156
+ ```
157
+
158
+ Prints a formatted table with best values marked (`*`).
159
+
160
+ ### Compute metrics on custom predictions
161
+
162
+ ```python
163
+ from depth_estimation.evaluation import DepthMetrics, Evaluator
164
+
165
+ # Per-prediction
166
+ metrics = DepthMetrics()
167
+ result = metrics(pred_tensor, gt_tensor, valid_mask)
168
+
169
+ # Accumulate correctly across batches (proper RMSE, not mean-of-means)
170
+ ev = Evaluator()
171
+ for pred, gt, mask in dataloader:
172
+ ev.update(pred, gt, mask)
173
+ final = ev.compute()
174
+ ```
175
+
176
+ ### Profile latency
177
+
178
+ ```python
179
+ from depth_estimation.evaluation import profile_latency
180
+
181
+ p = profile_latency("depth-anything-v2-vitb", num_runs=100)
182
+ print(f"{p['mean_ms']:.1f} ms | {p['fps']:.1f} FPS | {p['memory_mb']:.0f} MiB")
183
+ ```
184
+
185
+ Metrics: `abs_rel`, `sq_rel`, `rmse`, `rmse_log`, `delta1` / `delta2` / `delta3`.
186
+
187
+ See [docs/evaluation.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/evaluation.md) for full documentation.
188
+
189
+ ### Evaluation scripts
190
+
191
+ Ready-to-run scripts are in `examples/`:
192
+
193
+ ```bash
194
+ # NYU Depth V2 (auto-downloads dataset)
195
+ python examples/eval_nyu.py --model depth-anything-v2-vitb
196
+ python examples/eval_nyu.py --compare # all models, comparison table
197
+
198
+ # KITTI Eigen (manual download required)
199
+ python examples/eval_kitti.py --model zoedepth --dataset-root /data/kitti
200
+
201
+ # DIODE (auto-downloads ~2.6 GB val set)
202
+ python examples/eval_diode.py --scene-type indoors
203
+
204
+ # Quick 50-sample sanity check on any script
205
+ python examples/eval_nyu.py --model depth-anything-v2-vits --num-samples 50
206
+
207
+ # Save results to JSON
208
+ python examples/eval_nyu.py --model depth-pro --output results/depth_pro_nyu.json
209
+ ```
210
+
211
+ ---
212
+
213
+ ## CLI
214
+
215
+ After installing the package, a `depth-estimate` command is available.
216
+
217
+ ```bash
218
+ # Single image → saves demo_depth.png
219
+ depth-estimate predict examples/demo.png --model depth-anything-v2-vitb
220
+
221
+ # Batch (directory or glob) → saves to results/
222
+ depth-estimate predict "images/*.jpg" --model depth-anything-v2-vitb --output-dir results/
223
+
224
+ # Video → saves side-by-side RGB | depth as MP4
225
+ depth-estimate predict video.mp4 --model depth-anything-v2-vitb --output depth_video.mp4
226
+
227
+ # Save raw float32 array (.npy) alongside the PNG
228
+ depth-estimate predict examples/demo.png --model depth-anything-v2-vitb --format both
229
+
230
+ # Change colormap
231
+ depth-estimate predict examples/demo.png --model depth-anything-v2-vitb --colormap inferno
232
+
233
+ # List all available models
234
+ depth-estimate list-models
235
+
236
+ # Show config details for a model
237
+ depth-estimate info depth-anything-v2-vitb
238
+
239
+ # Evaluate a model on NYU Depth V2 (auto-downloads ~2.8 GB)
240
+ depth-estimate evaluate --model depth-anything-v2-vitb --dataset nyu_depth_v2
241
+
242
+ # Quick 50-sample check
243
+ depth-estimate evaluate --model depth-pro --dataset nyu --num-samples 50
244
+
245
+ # Compare multiple models and save results
246
+ depth-estimate evaluate --compare --dataset nyu_depth_v2 --output results.json
247
+ ```
248
+
249
+ **Global flags** (`--device`, `--quiet`, `--verbose`) go before the subcommand:
250
+
251
+ ```bash
252
+ depth-estimate --device cpu --quiet predict examples/demo.png --model depth-anything-v2-vitb
253
+ ```
254
+
255
+ All subcommands support `--json` for machine-readable output. See [docs/cli.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/cli.md) for full documentation.
256
+
257
+ ---
258
+
259
+ ## Architecture
260
+
261
+ The library follows the **HuggingFace Transformers** modular design philosophy:
262
+
263
+ - **Single model, single file** — each model's architecture is self-contained
264
+ - **Shared processor** — preprocessing/postprocessing is not duplicated
265
+ - **Registry-based auto-loading** — new models self-register, no core changes needed
266
+ - **Config inheritance** — configs override only what differs from the base
267
+
268
+ ```
269
+ Input → Processor.preprocess() → Model.forward() → Processor.postprocess() → DepthOutput
270
+ ```
271
+
272
+ ## Adding a New Model
273
+
274
+ 1. Create `src/depth_estimation/models/your_model/`
275
+ 2. Add `configuration_your_model.py` (inherit `BaseDepthConfig`)
276
+ 3. Add `modeling_your_model.py` (inherit `BaseDepthModel`, single file)
277
+ 4. Add `__init__.py` with `MODEL_REGISTRY.register(...)`
278
+
279
+ That's it — `AutoDepthModel`, `AutoProcessor`, and `pipeline()` will automatically resolve your model. See [docs/adding_a_model.md](https://github.com/shriarul5273/depth_estimation/blob/main/docs/adding_a_model.md) for a step-by-step guide.
280
+
281
+ ---
282
+
283
+ ## Running Tests
284
+
285
+ ```bash
286
+ pip install -e ".[dev]"
287
+ pytest tests/ -v
288
+ ```
289
+
290
+ ---
291
+
292
+ ## Acknowledgments
293
+
294
+ This library builds upon the incredible work of the following research teams:
295
+
296
+ | Model | Repository |
297
+ |---|---|
298
+ | **Depth Anything v1** | [github.com/LiheYoung/Depth-Anything](https://github.com/LiheYoung/Depth-Anything) |
299
+ | **Depth Anything v2** | [github.com/DepthAnything/Depth-Anything-V2](https://github.com/DepthAnything/Depth-Anything-V2) |
300
+ | **Depth Anything v3** | [github.com/DepthAnything/Depth-Anything-V3](https://github.com/DepthAnything/Depth-Anything-V3) |
301
+ | **DINOv2** | [github.com/facebookresearch/dinov2](https://github.com/facebookresearch/dinov2) |
302
+ | **DepthPro** | [github.com/apple/ml-depth-pro](https://github.com/apple/ml-depth-pro) |
303
+ | **ZoeDepth** | [github.com/isl-org/ZoeDepth](https://github.com/isl-org/ZoeDepth) |
304
+ | **MiDaS** | [github.com/isl-org/MiDaS](https://github.com/isl-org/MiDaS) |
305
+ | **Pixel-Perfect Depth** | [github.com/gangweix/Pixel-Perfect-Depth](https://github.com/gangweix/Pixel-Perfect-Depth) |
306
+ | **Marigold-DC** | [github.com/prs-eth/Marigold-DC](https://github.com/prs-eth/Marigold-DC) |
307
+ | **MoGe** | [github.com/microsoft/MoGe](https://github.com/microsoft/MoGe) |
308
+ | **VGGT** | [github.com/facebookresearch/vggt](https://github.com/facebookresearch/vggt) |
309
+ | **OmniVGGT** | [github.com/Livioni/OmniVGGT](https://github.com/Livioni/OmniVGGT) |
310
+
311
+ ## License
312
+
313
+ MIT