MasksComp

LM entropy model baseline

Train (row-wise RLE token LM with optional 2D context):

python tools/train_lm_entropy.py \
  --data-root /path/to/data \
  --out-dir output/lm_rle_baseline \
  --epochs 5 \
  --batch-size 64 \
  --use-2d-context

MSDZip-style backbone option (--arch msdzip) for fixed-context prediction:

python tools/train_lm_entropy.py \
  --data-root /path/to/data \
  --out-dir output/lm_msdzip \
  --arch msdzip \
  --timesteps 16 \
  --vocab-dim 16 \
  --hidden-dim 128 \
  --ffn-dim 256 \
  --layers 4

Run codec matrix with an MSDZip checkpoint (same CLI):

PYTHONPATH=$(pwd) python tools/run_lm_codec_matrix.py \
  --data-root /path/to/data \
  --subdir warped_masks \
  --checkpoint output/lm_msdzip/checkpoints/best.pt \
  --splits-dir output/lm_msdzip/splits \
  --out-csv output/lm_msdzip/lm_matrix.csv

Note: codec scripts enable deterministic PyTorch ops. On CUDA this can require CUBLAS_WORKSPACE_CONFIG=:4096:8 (or :16:8) in your environment.

Evaluate ideal bits (cross-entropy) on split:

python tools/eval_lm_entropy.py \
  --data-root /path/to/data \
  --checkpoint output/lm_rle_baseline/checkpoints/best.pt \
  --split val \
  --splits-dir output/lm_rle_baseline/splits \
  --out-csv output/lm_val_metrics.csv

Row cache for large datasets

For large mask corpora (e.g. A2D2), precompute a row-wise RLE cache to avoid keeping all RowItem objects in RAM:

python tools/cache_row_tokens.py \
  --data-root /path/to/data \
  --subdir warped_masks \
  --cache-dir /path/to/data/cache_rle_row_v1 \
  --manifest-out /path/to/data/cache_rle_row_v1/manifest.csv \
  --include-above-features \
  --compress npz \
  --verify 2

Train using the cache (same model/loss code path, lazy row loading):

python tools/train_lm_entropy.py \
  --data-root /path/to/data \
  --subdir warped_masks \
  --out-dir output/lm_rle_cached \
  --row-cache-dir /path/to/data/cache_rle_row_v1 \
  --epochs 5

Evaluate with cache-backed rows:

python tools/eval_lm_entropy.py \
  --data-root /path/to/data \
  --checkpoint output/lm_rle_cached/checkpoints/best.pt \
  --split val \
  --splits-dir output/lm_rle_cached/splits \
  --row-cache-dir /path/to/data/cache_rle_row_v1 \
  --out-csv output/lm_val_metrics_cached.csv

A2D2 quickstart

1. Convert A2D2 RGB semantic labels to class-id masks in MasksComp layout:

PYTHONPATH=$(pwd) python tools/prepare_a2d2_semantic.py \
  --a2d2-root /path/to/a2d2 \
  --out-root output/a2d2_frontcenter_ids \
  --camera front_center \
  --out-subdir warped_masks

2. Train LM entropy model on the converted masks:

PYTHONPATH=$(pwd) python tools/train_lm_entropy.py \
  --data-root output/a2d2_frontcenter_ids \
  --subdir warped_masks \
  --out-dir output/a2d2_lm \
  --epochs 1

3. Run LM codec matrix evaluation with the same dataset root/subdir:

PYTHONPATH=$(pwd) python tools/run_lm_codec_matrix.py \
  --data-root output/a2d2_frontcenter_ids \
  --subdir warped_masks \
  --checkpoint output/a2d2_lm/checkpoints/best.pt \
  --splits-dir output/a2d2_lm/splits \
  --out-csv output/a2d2_lm/lm_matrix.csv

Change detection benchmark (conditional codelength)

1. Build pair lists for train/val:

python tools/make_pairs.py --dataset a2d2 --data-root DS --subdir warped_masks --splits-dir DS/splits --delta 1 --out-dir OUT/pairs
python tools/make_pairs.py --dataset facades --data-root DS_F --subdir warped_masks --splits-dir DS_F/splits --out-dir OUT/pairs

2. Build residual datasets (C and V):

python tools/build_residual_dataset.py --data-root DS --subdir warped_masks --pairs-csv OUT/pairs/a2d2_pairs_train.csv --out-root RES_A2D2

3. Benchmark conditional classic codecs:

python tools/bench_residual_codecs.py --data-root RES_A2D2 --splits-dir RES_A2D2/splits --split val --codecs lzma,zstd --levels 1,3,6,9 --out-csv OUT/conditional_classic/a2d2_residual_codecs.csv

4. Train/evaluate LM on residual_C and residual_V with existing tools/train_lm_entropy.py and tools/eval_lm_entropy.py, then merge:

python tools/merge_residual_lm.py --csv-c OUT/lm_resC/val_per_image.csv --csv-v OUT/lm_resV/val_per_image.csv --split val --out-csv OUT/conditional_nn/residual_lm_sum.csv

5. Tile surprise maps and metrics:

python tools/eval_change_tiles.py --mode classic_residual --data-root RES_A2D2 --pairs-csv OUT/pairs/a2d2_pairs_val.csv --split val --out-dir OUT/change_tiles/classic
python tools/eval_change_metrics.py --data-root DS --pairs-csv OUT/pairs/a2d2_pairs_val.csv --heatmap-dir OUT/change_tiles/classic/heatmaps_tiles --dataset a2d2 --split val --method classic_residual --out OUT/change_tiles/classic/metrics_change_tiles.csv

6. Paper artifacts (tables + optional top-K render):

python tools/make_paper_artifacts.py --cond-csv OUT/conditional_nn/residual_lm_sum.csv --metrics-csv OUT/change_tiles/classic/metrics_change_tiles.csv --tiles-csv OUT/change_tiles/classic/change_tiles_scores.csv --heat-root OUT/change_tiles/classic/heatmaps_tiles --out-dir output --render-topk 10