Source browser
examples/data/readme.md
Read the complete file below or download its original bytes. Line numbers provide stable links to a declaration or processing step.
File fingerprint
1# Public data used by the examples
2
3These ten prepared files supply recorded images, signals, events and handwritten
4digits for `example_real_data`. The executable reads their binary and text
5formats directly for CPU and GPU processing.
6
7[The metadata module](../../scripts/data_sources.py) holds the eight pinned
8upstream downloads, ten prepared-file fingerprints and complete model-training
9provenance. Use it to look up exact source selections, file layouts and training
10settings when adapting the examples to your own data.
11
12From the project root, verify the supplied files, then run the examples:
13
14```sh
15python3 scripts/prepare_datasets.py --verify
16./build/example_real_data
17./build/example_real_data --gpu es31
18```
19
20Verification checks local file sizes and hashes with Python's standard library.
21The ten runtime files have the layouts and fingerprints described below.
22
23## Satellite image
24
25`earth_rgb.bin` contains 64 by 64 RGB pixels as unsigned bytes, row by row, with
26three interleaved channels. It is 12,288 bytes. The source is the 800 by 800 JPEG
27served by NASA's [Blue Marble 2002 page](https://science.nasa.gov/resource/blue-marble-2002/):
28
29[Original JPEG download](https://assets.science.nasa.gov/dynamicimage/assets/science/psd/solar/2023/09/1/1-bluemarble_west-1.jpg?crop=faces%2Cfocalpoint&fit=clip&h=800&w=800).
30
31The checked download is 105,654 bytes with SHA-256
32`9824d30eca98594e73fd276388108ec1ee1ab494038e730fd378efc1aae4ffa6`.
33Credit: **NASA's Earth Observatory**. The applicable source notice is the
34[NASA images and media guidance](https://www.nasa.gov/nasa-brand-center/images-and-media/).
35
36Preparation decodes the JPEG to RGB with Pillow 10.2.0. Each output pixel takes
37source coordinate `floor((2*i + 1) * 800 / 128)` on each axis. Sampling retains
38the decoded RGB channel values. The example normalizes bytes when it needs float
39channels. This image feeds buffer chains, blur, corners, convolution, Fourier
40transforms, asynchronous jobs and compression checks.
41
42Bayer inputs are mosaics sampled from these RGB pixels. Corner checks compare
43numerical references and CPU/GPU outputs. RLE checks exact byte reconstruction
44and reports the input and encoded sizes.
45
46## Two-channel ECG recording
47
48`signal_ecg.bin` contains two channel-major arrays of 2,048 little-endian float32
49samples. The first array is lead MLII, and the second is V5. Values are in
50millivolts at the original 360 Hz sample rate. The file is 16,384 bytes.
51
52The source is George Moody and Roger Mark's
53[MIT-BIH Arrhythmia Database, version 1.0.0](https://physionet.org/content/mitdb/1.0.0/),
54record 100, DOI **10.13026/C2F305**, distributed through PhysioNet under the
55[Open Data Commons Attribution License 1.0](https://opendatacommons.org/licenses/by/1-0/).
56Retain that attribution when redistributing the prepared excerpt.
57
58| Original input | Selected bytes | SHA-256 |
59| --- | ---: | --- |
60| [100.hea](https://physionet.org/files/mitdb/1.0.0/100.hea) | Complete 143-byte header | `60ebc904c7bf3e04d142638d3fd5c903e8dc9f10f1ea3264e07926aa089ee75e` |
61| [100.dat](https://physionet.org/files/mitdb/1.0.0/100.dat) | HTTP range `bytes=0-6143` from the 1,950,000-byte recording | `bfd10bda039ed650bf1a29a57cbd08df3994736c45c9ba1bc16e62fe97ca271a` |
62
63Preparation decodes the first 2,048 pairs from WFDB format 212, sign-extends each
6412-bit sample, and applies `(ADC - 1024) / 200` using the original header's
65calibration. It stores all MLII samples before all V5 samples. The FFT, inverse
66FFT, frequency masks, windows, FIR and stateful biquad cases process these values.
67The checks measure waveform reconstruction and filter-output agreement on the
68recorded samples.
69
70## Event-camera recording
71
72`evt3_words.bin` contains the first 32,768 encoded words after the original RAW
73header. Words are little-endian uint16 and occupy 65,536 bytes.
74`evt3_header.txt` contains the exact preceding 166-byte ASCII header.
75
76The source is the **Prophesee laser sample, Gen4.1 sensor**, listed in the official
77[Prophesee sample recordings](https://docs.prophesee.ai/stable/datasets.html).
78That collection identifies its sample data as
79[CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/).
80
81[Original RAW download](https://kdrive.infomaniak.com/2/app/975517/share/71d66a09-e3b6-480b-ba94-a1509e8ab2c8/files/12198/download).
82The complete source is 341,306,299 bytes. Preparation requests HTTP range
83`bytes=0-69631`, a 69,632-byte prefix with SHA-256
84`a398733173c1e684b68ea737a448aebb0f59dec6aa9a76ba587bfca824b4d6aa`.
85It preserves the original header, encoded words, timestamps and coordinates.
86
87The fixture decodes to 21,950 CD records. Event positions are sensor pixel
88coordinates, and decoded timestamps use microseconds. With a three-pixel radius,
89128-event lookback and 10,000-microsecond time window, 500 records have suitable
90neighbors for accepted normal-flow fits. These numbers measure decoder output
91and fit acceptance. Flow validation compares independent temporal-plane fits and
92CPU/GPU results.
93
94## MNIST digit images and labels
95
96MNIST is credited to **Yann LeCun, Corinna Cortes and Christopher J. C. Burges**.
97The [CVDF mirror](https://github.com/cvdfoundation/mnist) records permission to
98host the original files. The [original author page](http://yann.lecun.com/exdb/mnist/)
99provides source information and credits. A separately hosted
100[MNIST dataset card](https://huggingface.co/datasets/ylecun/mnist/raw/main/README.md)
101declares MIT for that copy. The metadata identifies the hosting-permission notice
102and the dataset-card declaration separately for their respective copies.
103
104| Original archive | Bytes | SHA-256 |
105| --- | ---: | --- |
106| [train-images-idx3-ubyte.gz](https://storage.googleapis.com/cvdf-datasets/mnist/train-images-idx3-ubyte.gz) | 9,912,422 | `440fcabf73cc546fa21475e81ea370265605f56be210a4024d2ca8f203523609` |
107| [train-labels-idx1-ubyte.gz](https://storage.googleapis.com/cvdf-datasets/mnist/train-labels-idx1-ubyte.gz) | 28,881 | `3552534a0a558bbed6aed32b30c495cca23d567ec52cac8be1a0730e8010255c` |
108| [t10k-images-idx3-ubyte.gz](https://storage.googleapis.com/cvdf-datasets/mnist/t10k-images-idx3-ubyte.gz) | 1,648,877 | `8d422c7b0a1c1c79245a5bcf07fe86e33eeafee792b84584aec276f5a2dbc4e6` |
109| [t10k-labels-idx1-ubyte.gz](https://storage.googleapis.com/cvdf-datasets/mnist/t10k-labels-idx1-ubyte.gz) | 4,542 | `f7ae60f92e00ec6debd23a6088c31dbd2371eca3ffa0defaefb259924204aec6` |
110
111The archives contain 60,000 training images and 10,000 independent test images.
112Preparation validates the IDX headers and removes them. Pixels remain unsigned
113bytes in row-major 28 by 28 order. Labels are digit class bytes from zero to nine.
114
115| Prepared file | Selection and layout |
116| --- | --- |
117| `mnist_train.bin` | 128 images, 100,352 bytes. First 64 instances each of digits zero and one, retained in original training order |
118| `mnist_train_labels.bin` | 128 matching labels, 128 bytes |
119| `mnist_test.bin` | First 512 official test images, 401,408 bytes |
120| `mnist_labels.bin` | First 512 official test labels, 512 bytes |
121
122The metadata records all 128 original training indices. Native neural inputs use
123`pixel / 255`. The small ANN derives two stroke features, the small CNN samples
124an 8 by 8 image, and the transformer forms four tokens from sixteen 7 by 7 patch
125means. Their small training examples fit selected training batches. The 3D
126convolution input is a stack of digit images along a depth axis.
127
128## Prepared LeNet model and independent scores
129
130`lenet_weights.bin` holds **61,706 little-endian float32 parameters** in 246,824
131bytes. `lenet_reference.bin` holds **10,000 by 10 little-endian float32 logits**
132in 400,000 bytes, in original official test order. Both are generated by
133[train_lenet.py](../../scripts/train_lenet.py), with full settings and results in
134`TRAINING_PROVENANCE` inside [data_sources.py](../../scripts/data_sources.py).
135
136The model is a modern LeNet variant with full second-layer channel connectivity,
137ReLU activations, fixed average pooling and linear output logits. It supplies a
138two-pixel zero border around each 28 by 28 input, then runs seven native stages:
139
140| Stage | Output per image |
141| --- | --- |
142| 5 by 5 convolution, 1 to 6 channels, ReLU | 6 by 28 by 28 |
143| 2 by 2 average pool, stride 2 | 6 by 14 by 14 |
144| 5 by 5 convolution, 6 to 16 channels, ReLU | 16 by 10 by 10 |
145| 2 by 2 average pool, stride 2 | 16 by 5 by 5 |
146| Dense 400 to 120, ReLU | 120 values |
147| Dense 120 to 84, ReLU | 84 values |
148| Dense 84 to 10 | 10 raw class scores |
149
150Convolution weights use `[out,in,ky,kx]` order and dense weights use `[out,in]`
151order. Each layer's biases immediately follow its weights. Weight and bias
152offsets are respectively 0/150, 156/2556, 2572/50572, 50692/60772 and 60856/61696.
153The predicted class is the index of the greatest logit.
154
155The recorded preparation used all 60,000 training images for three epochs, Adam
156with learning rate 0.001, batches of 128, seed 12345 and eight CPU threads.
157Preparation versions were PyTorch 2.6.0+cpu and NumPy 1.26.4. Training mean cross
158entropies were 0.4789702771107356, 0.12624290428757667 and 0.08441878777146339.
159Independent evaluation used all 10,000 held-out images and measured 97.78%
160accuracy, with cross entropy 0.06259464472532272. Native examples compare logits
161against the independent scores and test accuracy against the original labels.
162Model preparation uses optional Python packages. Deployed inference uses the
163C++/GLSL pipeline and plain float arrays.
164
165## Prepared-file fingerprints
166
167| File | SHA-256 |
168| --- | --- |
169| `earth_rgb.bin` | `ed28281973e480d946477c1f9bd83b0749c81cdd3ec7a15c7c422250b3f4cf5d` |
170| `signal_ecg.bin` | `9631961944e9e04e17722f44d522a216891b4c5763b348eb69d0160abfe3da44` |
171| `evt3_words.bin` | `da20cc642f8a3ba95bfcc3fe758cb7feed98334ffcfdf598c63fa2266775e014` |
172| `evt3_header.txt` | `a767d8bb9bce0446440d582b635cf8ba126390edd043d9f56f59f78ff63d865f` |
173| `mnist_train.bin` | `b4e671ad6e9b4d02b6ef48194346fc857be35d2d0b9711d45913464271c1522e` |
174| `mnist_train_labels.bin` | `49994fd8dc3bf88c7dff6d9863bde8bbf0d96ff09b8e99b3aaa4fbfceab5d3bf` |
175| `mnist_test.bin` | `80d1589bb8ec86cbe5b156dc437990d35e226cf0a5c7dc8202fc5e58124eff1d` |
176| `mnist_labels.bin` | `828c90776b296fc6bbadc357389e4d66dd7819fbb1979982a700d983168da942` |
177| `lenet_weights.bin` | `327dd259df961e6ed9b8f9fc82d2cd56b1334ca7525f92403de9c6495d1fe8de` |
178| `lenet_reference.bin` | `e3623237df15d5671dbb5cfd04c072d58f3d14a31bc04fd6b80c1d29026195e5` |
179
180## Reproduce preparation and training
181
182From the project root, optional preparation uses Pillow for the JPEG. Downloading
183occurs only with `--fetch`. Cached sources are size- and SHA-256-checked before
184conversion, and recording downloads require the server to honor the exact range.
185
186```sh
187# Download missing checked inputs and prepare the sample data.
188python3 scripts/prepare_datasets.py --fetch
189# Reuse the checked local source cache.
190python3 scripts/prepare_datasets.py
191# Also unpack every official test image and label under build/datasets.
192python3 scripts/prepare_datasets.py --full-mnist
193# Verify prepared files using only Python's standard library.
194python3 scripts/prepare_datasets.py --verify
195```
196
197The default source cache is `build/datasets/upstream`. `--cache` chooses another
198source cache, `--output` chooses the prepared-data directory, and `--full-output`
199chooses the complete test-split directory. To prepare a separate data directory
200with the supplied model and full test split:
201
202```sh
203mkdir -p build/my-data
204cp examples/data/lenet_weights.bin examples/data/lenet_reference.bin build/my-data/
205python3 scripts/prepare_datasets.py --cache build/datasets/upstream \
206 --output build/my-data --full-output build/my-data/full \
207 --metadata build/my-data/data_sources.py --full-mnist
208```
209
210Preparation creates the eight recorded-input files. Copy the supplied model
211exports or train the model to add the two classifier files.
212
213Retraining uses PyTorch and NumPy. The command checks the same four pinned MNIST
214archives and writes the two
215plain binary exports, together with training settings, metrics and fingerprints:
216
217```sh
218python3 scripts/train_lenet.py --cache build/datasets/upstream \
219 --epochs 3 --batch-size 128 --seed 12345 --threads 8
220python3 scripts/prepare_datasets.py --verify
221```
222
223`--output` and `--metadata` can keep a new model and its metadata outside this
224directory. Framework versions and execution environment affect floating-point
225training results. Use the exported fingerprints to identify each trained model.
226
227After full preparation, evaluate all 10,000 held-out images with:
228
229```sh
230SHDR_FULL_MNIST_DIR=build/datasets ./build/example_real_data
231SHDR_FULL_MNIST_DIR=build/datasets ./build/example_real_data --gpu es31
232```
233
234`SHDR_DATA_DIR` selects an alternate small-fixture and model directory. These
235end-to-end evaluation timings include batch construction, reference comparisons
236and result reads. The benchmark tables measure completed resident pipeline
237operations.