Add project page link, architecture summary, and detailed usage instructions (#1)

- Add project page link, architecture summary, and detailed usage instructions (304bb409147d948deeb0d52f272c42aaf5f408e3)


Co-authored-by: Niels Rogge <nielsr@users.noreply.huggingface.co>

README.md

@@ -1,10 +1,10 @@
 ---
-license: apache-2.0
 datasets:
 - zeweizhang/TrajLoomDatasets
 language:
 - en
-pipeline_tag: video-to-video
+license: apache-2.0
+pipeline_tag: other
 tags:
 - trajectory
 - flow matching
@@ -12,6 +12,7 @@ tags:
 - motion
 - VAE
 ---
+
 <p align="center">
   <h1 align="center"><em>TrajLoom</em>: Dense Future Trajectory Generation from Video</h1>
   <div align="center">
@@ -30,7 +31,9 @@ tags:
     <strong>Renjie Liao</strong>
   </div>
   <br>
-  <div align="center">
+  <div align="center")>
+    <a href="https://trajloom.github.io/"><img src="https://img.shields.io/badge/Project-Page-green.svg" alt="Project Page"></a>
+    &nbsp;
     <a href="https://arxiv.org/abs/2603.22606"><img src="https://img.shields.io/badge/arXiv-Preprint-brightgreen.svg" alt="arXiv Preprint"></a>
     &nbsp;
     <a href="https://github.com/zewei-Zhang/TrajLoom">
@@ -44,7 +47,14 @@ tags:
 </p>
 
 ## Introduction
-TrajLoom is a framework for dense future trajectory generation from video. Given observed video and trajectory history, it predicts future point trajectories and visibility over a long horizon. The released checkpoints include TrajLoom-VAE, TrajLoom-Flow, and the visibility predictor used by the inference pipeline in the GitHub repository.
+TrajLoom is a framework for dense future trajectory generation from video, as described in the paper [TrajLoom: Dense Future Trajectory Generation from Video](https://arxiv.org/abs/2603.22606). Given an observed video and trajectory history, it predicts future point trajectories and visibility over a long horizon (extending the horizon from 24 to 81 frames). 
+
+The framework consists of three main components:
+1. **Grid-Anchor Offset Encoding**: Reduces location-dependent bias by representing points as offsets from anchors.
+2. **TrajLoom-VAE**: Learns a compact spatiotemporal latent space for dense trajectories.
+3. **TrajLoom-Flow**: Generates future trajectories in the latent space via flow matching.
+
+The released checkpoints include TrajLoom-VAE, TrajLoom-Flow, and the visibility predictor.
 
 ## Download the model
 ### Option 1: clone the full repository
@@ -68,7 +78,7 @@ hf download zeweizhang/TrajLoom trajloom_visibility.pt --local-dir ./TrajLoom
 ```
 
 ## How to use with the GitHub repo
-Copy the downloaded checkpoints into the `models/` folder of the GitHub repository:
+First, clone the [GitHub repository](https://github.com/zewei-Zhang/TrajLoom) and install the environment. Copy the downloaded checkpoints into the `models/` folder:
 
 ```text
 TrajLoom/
@@ -78,11 +88,35 @@ TrajLoom/
 │   └── trajloom_visibility.pt
 ```
 
-Then follow the inference instructions in the GitHub repo:
+### Future Trajectory Generation
+Run the generator to predict future trajectories from observed history:
+
+```bash
+python run_trajloom_generator.py \
+  --gen_config configs/trajloom_generator_config.json \
+  --gen_ckpt models/trajloom_generator.pt \
+  --vis_config configs/vis_predictor_config.json \
+  --vis_ckpt models/trajloom_visibility.pt \
+  --video_dir "/path/to/videos/" \
+  --video_glob "*.mp4" \
+  --gt_dir "/path/to/ground_truth/tracks/" \
+  --out_dir "/path/to/output/" \
+  --pred_len 81
+```
 
-- `run_trajloom_generator.py` for future trajectory generation
-- `run_trajloom_vae_recon.py` for VAE reconstruction
+### VAE Reconstruction
+Use the VAE reconstruction script to verify that your trajectory data and latent statistics are configured correctly:
 
+```bash
+python run_trajloom_vae_recon.py \
+  --config configs/trajloom_vae_config.json \
+  --video_dir "/path/to/videos/" \
+  --video_glob "*.mp4" \
+  --gt_dir "/path/to/ground_truth/tracks/" \
+  --out_dir "/path/to/output/" \
+  --pred_len 81 \
+  --save_video
+```
 
 ## Citation
 ```bibtex