Flor commited on
Commit
f577d16
·
0 Parent(s):

fastforks 0.1.0

Browse files
Files changed (2) hide show
  1. .gitattributes +35 -0
  2. README.md +124 -0
.gitattributes ADDED
@@ -0,0 +1,35 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ *.7z filter=lfs diff=lfs merge=lfs -text
2
+ *.arrow filter=lfs diff=lfs merge=lfs -text
3
+ *.bin filter=lfs diff=lfs merge=lfs -text
4
+ *.bz2 filter=lfs diff=lfs merge=lfs -text
5
+ *.ckpt filter=lfs diff=lfs merge=lfs -text
6
+ *.ftz filter=lfs diff=lfs merge=lfs -text
7
+ *.gz filter=lfs diff=lfs merge=lfs -text
8
+ *.h5 filter=lfs diff=lfs merge=lfs -text
9
+ *.joblib filter=lfs diff=lfs merge=lfs -text
10
+ *.lfs.* filter=lfs diff=lfs merge=lfs -text
11
+ *.mlmodel filter=lfs diff=lfs merge=lfs -text
12
+ *.model filter=lfs diff=lfs merge=lfs -text
13
+ *.msgpack filter=lfs diff=lfs merge=lfs -text
14
+ *.npy filter=lfs diff=lfs merge=lfs -text
15
+ *.npz filter=lfs diff=lfs merge=lfs -text
16
+ *.onnx filter=lfs diff=lfs merge=lfs -text
17
+ *.ot filter=lfs diff=lfs merge=lfs -text
18
+ *.parquet filter=lfs diff=lfs merge=lfs -text
19
+ *.pb filter=lfs diff=lfs merge=lfs -text
20
+ *.pickle filter=lfs diff=lfs merge=lfs -text
21
+ *.pkl filter=lfs diff=lfs merge=lfs -text
22
+ *.pt filter=lfs diff=lfs merge=lfs -text
23
+ *.pth filter=lfs diff=lfs merge=lfs -text
24
+ *.rar filter=lfs diff=lfs merge=lfs -text
25
+ *.safetensors filter=lfs diff=lfs merge=lfs -text
26
+ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
27
+ *.tar.* filter=lfs diff=lfs merge=lfs -text
28
+ *.tar filter=lfs diff=lfs merge=lfs -text
29
+ *.tflite filter=lfs diff=lfs merge=lfs -text
30
+ *.tgz filter=lfs diff=lfs merge=lfs -text
31
+ *.wasm filter=lfs diff=lfs merge=lfs -text
32
+ *.xz filter=lfs diff=lfs merge=lfs -text
33
+ *.zip filter=lfs diff=lfs merge=lfs -text
34
+ *.zst filter=lfs diff=lfs merge=lfs -text
35
+ *tfevents* filter=lfs diff=lfs merge=lfs -text
README.md ADDED
@@ -0,0 +1,124 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ library_name: "fastforks"
3
+ pipeline_tag: "depth-estimation"
4
+ license: "other"
5
+ license_name: "apache-2.0-code-weights-unstated"
6
+ license_link: "https://github.com/megvii-research/CREStereo/blob/ad3a1613bdedd88b93247e5f002cb7c80799762d/README.md#L82"
7
+ tags:
8
+ - "stereo"
9
+ - "stereo-matching"
10
+ - "disparity"
11
+ - "cuda"
12
+ - "pytorch"
13
+ - "fastforks"
14
+ ---
15
+ # CREStereo (fastforks)
16
+
17
+ CREStereo (Li et al. 2022): cascaded recurrent stereo with adaptive group correlation (2-D / 1-D local search, learned offsets, cross attention at 1/16), a 1/16 -> 1/8 -> 1/4 GRU cascade and two passes (half, then full resolution) of 20 iterations each.
18
+
19
+ This repo is the model card only: it holds no weights. fastforks downloads the authors' weights from the links below and checks them against the SHA-256 in the model card. Code: <https://github.com/kleinicke/fastforks>. Kernels for the `kernels` backend: <https://huggingface.co/fastforks/kernels>. Original code: <https://github.com/megvii-research/CREStereo> at `ad3a1613bded`.
20
+
21
+ Task: stereo. Tier: experimental. Outputs: `disparity`. Backends: `portable`, `kernels`.
22
+
23
+ Input: a rectified left / right image pair. Output: a disparity map (pixels, left view).
24
+
25
+ ## Variants
26
+
27
+ Weights are the authors' files (not hosted here). SHA-256 shortened to 12 hex digits; the full hashes are in [`card.toml`](https://github.com/kleinicke/fastforks/blob/main/src/fastforks/stereo/models/crestereo/card.toml).
28
+
29
+ | variant | weights (author link) | SHA-256 | weights licence | commercial use |
30
+ |---|---|---|---|---|
31
+ | `crestereo-eth3d@1` | [crestereo_eth3d.mge](https://drive.usercontent.google.com/download?id=1Wx_-zDQh7BUFBmN9im_26DFpnf3AkXj4&export=download&confirm=t) | `6a11b16a121d` | Apache-2.0 (assumed from code) | yes |
32
+
33
+ ## Licence
34
+
35
+ Original-code strings, recorded as they are (research-use package; check them before any other use). Code: Apache-2.0. Files: `LICENSE`.
36
+
37
+ Code licence: Apache-2.0; the authors do not state a separate weights licence.
38
+
39
+ Training data: CREStereo synthetic stereo dataset (Megvii), Freiburg SceneFlow (FlyingThings3D, Driving, Monkaa), MPI Sintel stereo, Middlebury stereo (2014), ETH3D two-view stereo, KITTI stereo 2012 / 2015, NVIDIA Falling Things (FAT), InStereo2K, HR-VS (high-resolution virtual stereo, Yang et al. CVPR 2019) (the datasets original README lists as used for training; which of them the released checkpoint saw is not stated).
40
+
41
+ Licence evidence: <https://github.com/megvii-research/CREStereo/blob/ad3a1613bdedd88b93247e5f002cb7c80799762d/README.md#L82>
42
+
43
+ ## Input size
44
+
45
+ any H x W >= 33, padded to a multiple of 32
46
+ Tested up to (portable, fp16, RTX 5060 Ti 16 GB): `crestereo-eth3d` 3000x4000 (6.4 GiB peak allocated, 8.8 reserved)
47
+
48
+ ## Speed and memory
49
+
50
+ ### Stereo, Middlebury 2014 half, 994x1482
51
+
52
+ | model | time (ms): original fp32 | original | portable | kernels | kernels speed-up: vs original | vs portable | peak memory (MiB, allocated / reserved): original | portable | kernels |
53
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
54
+ | `crestereo-eth3d` | – | 1925 | 732 | 229 | 8.4x | 3.2x | – | 884 / 1030 | 644 / 732 |
55
+
56
+ ### Startup and first call
57
+
58
+ | model | load (s): original | portable | kernels | first call (s): original | portable | kernels |
59
+ | --- | --- | --- | --- | --- | --- | --- |
60
+ | `crestereo-eth3d` | – | 0.03 | 0.03† | – | 0.75† | 0.23† |
61
+
62
+ ### torch.compile and TensorRT
63
+
64
+ | model | input | portable ms | compile ms | compile s (cold) | TensorRT fp16 ms | ONNX + build s | kernels ms | peak MiB (alloc / reserved): portable | compile | TensorRT (device) |
65
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
66
+ | `crestereo-eth3d` | 994x1482 | 732 | 397.7 | 120.3 | 297.8 | 224 | 229 | 884 / 1030 | 695 / 748 | 584 |
67
+
68
+ ### Fixed-size speed and peak memory, all models
69
+
70
+ | model | mode | 480x640 | 720x1280 | 1080x1920 | 12 MP 3000x4000 |
71
+ | --- | --- | --- | --- | --- | --- |
72
+ | `crestereo-eth3d` | portable | 142.5 ms / 214 / 284 | 427.8 ms / 556 / 740 | 1022.9 ms / 1172 / 1568 | 6466.7 ms (n=3) / 6508 / 8990 |
73
+ | `crestereo-eth3d` | kernels | 61.8 ms / 216 / 292 | 145.2 ms / 552 / 792 | 311.2 ms / 1162 / 1638 | 1767.7 ms / 6427 / 9362 |
74
+
75
+ ### Apple silicon (MPS)
76
+
77
+ | model | `portable` | `kernels` | speed-up |
78
+ | --- | --- | --- | --- |
79
+ | `crestereo-eth3d` | 1265 ms / 1597 MiB (float16) | 1104 ms / 1642 MiB | 1.15x |
80
+
81
+ Fixed-size cells: time (ms) / peak allocated / peak reserved memory (MiB).
82
+
83
+ Hardware, protocol and caveats: [benchmarks](https://github.com/kleinicke/fastforks/blob/main/docs/benchmarks.md) (RTX 5060 Ti 16 GB, sm_120). Original = the authors' code at the precision of portable (fp16, or `(fp32)` where fp16 is unsupported or not finite); original fp32 = its default fp32 run. Peak memory is the torch allocator's.
84
+
85
+ ## Accuracy
86
+
87
+ ### On public datasets
88
+
89
+ Original = the authors' code, same checkpoint and protocol.
90
+
91
+ | variant | dataset | original fp32 | portable | kernels | note |
92
+ |---|---|---|---|---|---|
93
+ | `crestereo-eth3d` | ETH3D two-view train, bad > 1 px % / EPE | 1.40 / 0.185 | 1.39 / 0.184 | 1.39 / 0.184 | trained on this dataset's public images; not a zero-shot result |
94
+ | `crestereo-eth3d` | Middlebury 2014 trainingH, bad > 2 px % / EPE | 5.16 / 0.753 | 4.84 / 0.699 | 4.86 / 0.693 | trained on this dataset's public images; not a zero-shot result |
95
+
96
+ Measured on NVIDIA GeForce RTX 5060 Ti, torch 2.14.1+cu130, 2026-11-05.
97
+
98
+ ### Parity with the original code
99
+
100
+ Every variant is checked against reference outputs of the original code at its pinned commit. CPU, float32: max |diff| <= 0.002 vs the original. GPU, float16 (the default), portable and kernels: mean |diff| <= 0.02 px and p99 <= 0.25 px.
101
+
102
+ ## Limitations
103
+
104
+ - CUDA output (float16, kernels, float32 with PyTorch's default TF32 convolutions) differs from the CPU by ~0.1-0.2 px mean / 3 px p99 at 720x1280, 0.03 px with full float32: rounding amplified by 2 x 20 GRU iterations. Portable and kernels reach the same ETH3D / Middlebury accuracy.
105
+ - Middlebury accuracy differs from the original code (about -0.3 bad-%; the original run padded differently).
106
+
107
+ ## Usage
108
+
109
+ ```python
110
+ from fastforks import stereo
111
+
112
+ model = stereo.load("crestereo-eth3d") # mode="auto": the preferred backend from recorded measurements
113
+ result = model("left.png", "right.png")
114
+ result.disparity # [H, W] float32 tensor, input resolution
115
+ result.backend # what ran, e.g. Backend(mode='portable', device='cuda:0', dtype='float16')
116
+ ```
117
+
118
+ Install with `pip install fastforks` (see <https://github.com/kleinicke/fastforks>). Other variants: `crestereo-eth3d`.
119
+
120
+ ## Kernels backend
121
+
122
+ `stereo.load("crestereo-eth3d", mode="kernels")` runs our CUDA kernels (`crestereo`, `fastbb`, `igev`, `cutlass_conv`, `cudnn_hacc`). It needs a prebuilt kernel for your GPU architecture (downloaded from <https://huggingface.co/fastforks/kernels> on first use) and a recent NVIDIA driver; if there is none it raises `BackendUnavailableError` with the reason and never falls back silently. `mode="auto"` picks `kernels` when it can run and logs the choice.
123
+
124
+ <!-- staged from fastforks feccac41 (2026-11-06) -->