How fredfung007/cityflow-nl works
Project Type and Purpose
• This is an open-source baseline toolkit for a research challenge (AI City NLP vehicle retrieval).
• It provides data utilities, a configurable pipeline, a Siamese-style retrieval model, evaluation scripts, and example outputs.
File Structure
Top-level directories:
• data/
• JSON data files (train-tracks, test-tracks, test-queries)
• Script to extract frames (extract_vdo_frms.py)
• baseline/
• Configuration (config.py, default.yaml)
• Dataset definition (vehicle_retrieval_dataset.py)
• Model code (siamese_baseline_model.py)
• Workflow orchestration (workflow.py)
• Evaluation (evaluate.py)
• Submission prep (prepare_output_json.py)
• Utilities (utils.py)
• Requirements (requirements.txt)
• Sample results (baseline-results.json)
README for Insights
• The core pipeline: frame extraction → data loading → model inference → ranking → evaluation → submission JSON.
• Emphasis on MRR and Recall metrics.
• Configurable via default.yaml.
Main Components and Interactions
a. Data Storage & Input
• Source JSONs: train-tracks.json, test-tracks.json, test-queries.json
• Frame extraction script reads video sources (CityFlow benchmark) and writes image frames
b. Configuration Service
• default.yaml (hyperparameters, file paths)
• config.py loads and exposes settings
c. Data Preparation Module
• vehicle_retrieval_dataset.py: wraps JSON + frame files into dataset objects
• utils.py: helper functions (e.g., text processing, image loading)
d. Workflow Orchestrator
• workflow.py: CLI entry point that ties together dataset, model, evaluation, and output generation
e. Model Module
• siamese_baseline_model.py: implements the Siamese-style embedding model for text + image similarity
f. Inference & Ranking
• Within workflow.py, runs model over all query embeddings vs. track embeddings to rank candidates
g. Evaluation Module
• evaluate.py: computes MRR, Recall@5, Recall@10 against ground truth
h. Submission Preparation
• prepare_output_json.py: converts ranked lists into the required submission JSON format
i. Outputs
• baseline-results.json: sample submission / model outputs
Architectural Patterns & Design Principles
• Modular pipeline: each stage (data prep, model, evaluation) is a separate module
• Configuration-driven: default.yaml drives file paths, model parameters
• Single-process CLI orchestration (no microservices)
• Clear separation of concerns: data, model, evaluation, I/O
Detailed Component Breakdown
• Raw JSON files (train-tracks.json, test-tracks.json, test-queries.json)
• Extracted Frames (output of extract_vdo_frms.py)
[Configuration – Green Rectangle]
• default.yaml → config.py
[Data Prep – Green Oval]
• vehicle_retrieval_dataset.py
• utils.py
[Model – Green Rectangle]
• siamese_baseline_model.py
[Workflow Orchestrator – Green Diamond]
• workflow.py (CLI entry)
[Evaluation – Green Oval]
• evaluate.py
[Submission Prep – Green Oval]
• prepare_output_json.py
• baseline-results.json (submission)
Summary of Steps for the Engineer
1. Sketch the Data Layer on the left, Configuration above or next to it.
3. Dataset loader to the Model component.