Env-Rec-OSM-WAIRD

Codebase for the paper: Fusion of pervasive RF data with spatial images via vision transformers for enhanced mapping in smart cities

1) Environment setup

conda env create
conda activate env_rec_osm_waird

Create a .env file in the repository root (it is loaded by run.py) and define:

OUTPUT_DIR=/absolute/path/to/outputs
PREDICTIONS_PATH=/absolute/path/to/predictions
AIM_REPO=/absolute/path/to/aim_repo

R_IMAGES_DATA_PATH=/absolute/path/to/waird/images
R_DIST_TRANSFORM_PATH=/absolute/path/to/waird/dist_transform   # or keep empty if not used
SEQUENCE_DATA_PATH=/absolute/path/to/waird/sequences
SCENARIO2_PATH=/absolute/path/to/waird_scenario2/images/scenario_2

OSLO_MAT_FILE=/absolute/path/to/oslo/measurements.mat
OSLO_CELL_FILE=/absolute/path/to/oslo/cell_info.xlsx
OSLO_IMAGES_OUT_DIR=/absolute/path/to/oslo/generated/images
OSLO_SEQUENCES_OUT_DIR=/absolute/path/to/oslo/generated/sequences
OSLO_SPLITS_PATH=/absolute/path/to/oslo/splits
OSLO_STITCH_ARTIFACTS=/absolute/path/to/oslo/stitch_artifacts

2) Data download

• WAIR-D dataset: Download page
• Oslo dataset (4G/NB-IoT/5G NSA measurements): IEEE DataPort page

3) WAIR-D workflow (train / inference / evaluation / visualization)

Train

python run.py --config-name=train

Inference

python run.py --config-name=inference checkpoint_path=/absolute/path/to/checkpoint.ckpt split=test gpu=0

Evaluation

python run.py --config-name=evaluation \
  prediction_path=/absolute/path/to/predictions/<run>/<ckpt>/wair_d_r_osm_sequences/test \
  task=osm split=test

Reconstruction visualization (Streamlit)

python run.py --config-name=reconstruction_visualize \
  predictions_path=/absolute/path/to/predictions/<run>/<ckpt>/wair_d_r_osm_sequences/test

4) Oslo data generation and prep

Generate Oslo environments (images + sequences)

python run.py --config-name=oslo_generate_data

(Optional) Retrofit generated sequence metadata

python run.py --config-name=oslo_retrofit_info

Split Oslo environments into train/val/test

python run.py --config-name=oslo_train_test_split

(Optional) Build info_*.json for filtering/analysis

python run.py name=oslo_create_info_json print_config=False main_path=/absolute/path/to/scenario_1 dataset_type=dataSet_interp

5) Oslo model training / inference / evaluation / visualization

Train on Oslo split

python run.py --config-name=train datamodule=oslo

Inference on Oslo split

python run.py --config-name=inference datamodule=oslo checkpoint_path=/absolute/path/to/checkpoint.ckpt split=test gpu=0

Evaluation on Oslo split

python run.py --config-name=evaluation \
  datamodule=oslo \
  prediction_path=/absolute/path/to/predictions/<run>/<ckpt>/oslo/test \
  task=osm split=test

Reconstruction visualization for Oslo predictions

python run.py --config-name=reconstruction_visualize \
  datamodule=oslo \
  predictions_path=/absolute/path/to/predictions/<run>/<ckpt>/oslo/test

6) Oslo stitching pipeline (full-area inference)

Run in this order:

6.1 Build full-area artifact

python run.py --config-name=oslo_build_full_area

6.2 Generate crop cache

python run.py --config-name=oslo_generate_crop_cache

6.3 Stitch inference (single setting)

python run.py --config-name=oslo_stitch_inference \
  checkpoint_path=/absolute/path/to/checkpoint.ckpt \
  gpu=0 \
  window_fraction=1/16 \
  fallback_mode=input_map

6.4 Stitch inference sweep (all fractions and fallback modes)

bash scripts/oslo_stitch_sweep.sh

6.5 Stitch evaluation

python run.py --config-name=oslo_stitch_evaluate checkpoint_path=/absolute/path/to/checkpoint.ckpt

6.6 Stitch visualization (Streamlit)

python run.py --config-name=oslo_stitch_visualize