Practical guide
Run pipelines on public data
example_real_data runs processing pipelines on recorded images, waveforms, events and handwritten digits. The prepared files live in examples/data. Ordinary C++ builds and application runs read those binary files directly.
# Check the supplied local input and model files.
python3 scripts/prepare_datasets.py --verify
# Run every real-data case on the CPU.
./build/example_real_data
# Run the same cases with an ES 3.1 headless device.
./build/example_real_data --gpu es31
GPU runs start from the same inputs and mutable state as their CPU references. They compare complete outputs, including intermediate resources and learned parameters. The individual examples also retain their independent numerical references and seeded edge cases.
Know what each input measures
| Public input | Processing cases | What is checked |
|---|---|---|
| NASA Blue Marble RGB image | Linked buffers, mixed CPU/GPU stages, asynchronous jobs, image blur, corners, 2D convolution and Fourier transforms | Complete backend output comparisons, independent arithmetic and blur references, inverse reconstruction |
| Bayer samples derived from the NASA image | Four Bayer phases and four packing formats, followed by interpolation and luminance | Exact packing round trips and CPU/GPU color results |
| NASA RGB byte values | Tiled RLE encoding and decoding | Exact reconstruction of all original values, with actual encoded size reported |
| PhysioNet two-channel ECG prefix | Batched 1D FFT, inverse FFT, frequency masks, windows, FIR and biquad filters | Backend comparisons and waveform reconstruction |
| Prophesee laser EVT3 recording prefix | Ordered decoding, compact CD events and normal optical flow | Exact decoded records, independent temporal-plane fits and backend comparisons |
| MNIST digit image stack | 3D convolution | Every output sample compared between backends |
| MNIST zero/one training samples | Small ANN, CNN and transformer training and prediction | Falling mini-batch loss and complete parameter, gradient and prediction comparisons |
| Official MNIST test images and trained LeNet weights | Seven-stage deeper classifier inference | Original test labels and independent PyTorch reference logits |
The Bayer input is a color mosaic sampled from the published RGB image. The 3D input stacks digit images along a depth axis. These cases measure packing, interpolation, convolution and backend agreement. The satellite image supports numerical corner checks, and the event recording supports decoder and temporal-plane-fit checks. The ECG case measures signal-processing behavior. The separate digit classifier uses held-out labels to measure classification accuracy.
The prepared EVT3 prefix decodes to 21,950 CD records. With a three-pixel radius, 128-event lookback and 10,000-microsecond time window, 500 records have enough suitable neighbors for accepted normal-flow fits. These counts measure decoded output and fit acceptance.
RLE can expand a photograph's byte values. Its exact round trip remains useful even when its encoded size is larger. The small neural training cases fit one selected training mini-batch. Their reported loss is a training measure. The separate LeNet evaluation uses held-out test labels.
Reproduce the prepared files
Preparation checks pinned input files before decoding them. Large recordings use bounded HTTP byte ranges. The data reference describes the source downloads, preprocessing and file layouts.
Use the supplied inputs to reproduce the examples, or follow the documented layouts to supply your own data. Run python3 scripts/prepare_datasets.py --verify to check the prepared inputs and model files before evaluation.
Install Pillow for the JPEG preparation step, then run:
# Download only missing pinned public inputs and prepare the small fixtures.
python3 scripts/prepare_datasets.py --fetch
# Also unpack all 10,000 official MNIST test images into the build cache.
python3 scripts/prepare_datasets.py --full-mnist
Later preparation can reuse build/datasets/upstream. Use --fetch when downloading missing source files. --cache and --output select other directories. --verify checks prepared files using Python's standard library and the supplied source records. JPEG decoder versions can affect the final RGB values, so use the supplied prepared image for matching inputs across systems.
| Prepared file | Layout and transformation |
|---|---|
earth_rgb.bin |
64×64 RGB8 pixels in row-major interleaved order. Decode the checked 800×800 JPEG, then sample each destination pixel's source center with nearest-neighbor indexing |
signal_ecg.bin |
Two arrays of 2048 little-endian float32 samples, MLII followed by V5, at 360 Hz. Decode WFDB format 212 and apply (ADC - 1024) / 200 millivolts |
evt3_words.bin |
First 32768 little-endian uint16 words after the original 166-byte RAW header. Encoded words and absolute timestamps are retained |
evt3_header.txt |
Exact original ASCII header from that recording prefix |
mnist_train.bin / mnist_train_labels.bin |
First 64 training instances each of zero and one, retained in original training order. Raw 28×28 image bytes and matching labels, with original indices recorded |
mnist_test.bin / mnist_labels.bin |
First 512 official test images and matching labels, retained in original test order |
The image resize uses source coordinate floor((2*destination_index + 1) * source_size / (2*64)) on each axis and retains the decoded RGB transfer values. Runtime image processing normalizes bytes and applies its documented luminance weights. Neural inputs are divided by 255, and LeNet supplies a two-pixel zero border.
The small ANN uses horizontal stroke spread and outer-versus-center ink as its two features. The small CNN samples an 8×8 image with center-nearest indexing. The transformer uses four tokens, each containing four means of 7×7 pixel patches. These feature transformations are in real_data.cpp. They retain the original binary digit labels.
Evaluate the full digit test split
Full MNIST preparation writes mnist_full.bin and mnist_full_labels.bin into
build/datasets. The evaluator accepts that directory for its LeNet test case:
# Evaluate all 10,000 held-out images with native CPU inference.
SHDR_FULL_MNIST_DIR=build/datasets ./build/example_real_data
# Evaluate the same complete test split with native GPU inference.
SHDR_FULL_MNIST_DIR=build/datasets ./build/example_real_data --gpu es31
Other real-data cases still use their small fixtures. SHDR_DATA_DIR selects an
alternate directory for those files and the model bundle. The classifier reports
the number of correct original labels and the greatest normalized difference
from the independent framework logits. These evaluation timings include batch
construction, comparisons and result reads. They have a different scope from
the resident-pipeline benchmark table.
The recorded full evaluations produced 9778 correct labels out of 10,000, or 97.78%, on the Ryzen CPU and llvmpipe, the Core i7 CPU and Iris Xe, and the Pi 5 CPU and V3D. Every native score matched the independent framework reference within a maximum normalized error of 4.57699e-6. The complete results record each backend's exact error, completed evaluation time and model and input fingerprints.
Credit and data terms
The NASA Blue Marble 2002 page credits NASA's Earth Observatory. It is a composite of actual MODIS satellite observations. The example retains that credit and uses it for a factual processing demonstration under the NASA media guidelines.
The ECG source is George Moody and Roger Mark's MIT-BIH Arrhythmia Database, version 1.0.0, record 100, DOI 10.13026/C2F305. Its data terms are the Open Data Commons Attribution License 1.0. The retained prefix contains the first 2048 sample pairs from the two recorded leads, with calibration taken from the original header.
The laser recording is from the official Prophesee sample recordings. That collection identifies its sample files as CC0 1.0. The fixture uses an exact prefix of its Gen4.1 EVT3 RAW recording.
MNIST is credited to Yann LeCun, Corinna Cortes and Christopher J. C. Burges. The CVDF mirror records the author's permission to host the original files. Consult that permission record and the original author page for the mirrored archives' terms. The separately hosted MNIST dataset card labels its copy MIT. The source records retain each copy's stated terms.
The model weights and framework logits are generated by train_lenet.py. Their settings, input fingerprints, held-out metrics and output fingerprints are in training provenance. The neural guide explains the model architecture and optional preparation dependencies.