README.md

metadata

title: Codebook
emoji: 📚
colorFrom: pink
colorTo: indigo
sdk: static
pinned: false

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Human-Robot Collaboration Failure Codebook

• browse all failure categories
• open a category detail page with its definition and representative example
• inspect every coded segment attached to that category
• search all coded segments across the dataset

Project Structure

.
|-- index.html                  # Homepage with failure category cards
|-- category.html               # Detail page for one failure category
|-- all_videos.html             # Searchable table of all coded segments
|-- assets/
|   |-- css/                    # Shared and page-specific styles
|   `-- js/
|       |-- failures.js         # Failure definitions and metadata
|       |-- homepage.js         # Homepage search + category stats
|       |-- category.js         # Category page rendering
|       |-- all_videos.js       # All-videos table rendering
|       `-- video_segment.js    # Video loop/playback behavior
|-- raw_data.csv                # Original Label Studio export
|-- cleaned_data.csv            # Flattened CSV used by the web app
|-- clean.py                    # Converts raw_data.csv -> cleaned_data.csv
`-- videos/                     # Source MP4 files referenced by the app

Data Files

raw_data.csv

This is the original annotation export. It contains:

• id
• participant
• condition
• run
• filename
• videoLabels

The videoLabels column stores Label Studio timeline annotations as JSON.

cleaned_data.csv

This is the flattened file the app actually uses. It contains one row per coded label occurrence:

• filename
• video_id
• video_path
• label
• start
• end

Video Playback Rules

Segment playback behavior is implemented in assets/js/video_segment.js.

Each embedded video:

• lazy-loads when it gets near the viewport
• starts from a computed frame-based window
• loops only within the relevant segment
• respects manual pause and scrubbing

Some labels have custom playback behavior. For example:

• Success and Failure play the full video
• Safety Avoidance and Redundant Retrieval play from the annotated start to the end of the video
• Missed Grab and Slippage expand the playback window around the annotation

Default FPS is set to 30.

Typical Update Workflow

1. Replace or update raw_data.csv.
2. Run python3 clean.py.
3. Confirm cleaned_data.csv was regenerated correctly.
4. Add or update files in videos/ if needed.
5. Start a local server and verify index.html, category.html, and all_videos.html.

Current Dataset Snapshot

At the time of this README update, the repository contains:

• 288 data rows in raw_data.csv excluding the header
• 657 data rows in cleaned_data.csv excluding the header