README.md

LMDB Tool

Tools for converting RoboInter annotation data from pkl (data link) format to LMDB (data link), and for reading/validating the resulting LMDB files.

---

Directory Structure

lmdb_tool/
├── convert_pkl_to_lmdb.py   # Convert merged pkl files to frame-level LMDB
├── read_lmdb.py              # Read, inspect, and validate LMDB files
└── README.md

---

LMDB Data Format

Each LMDB key corresponds to an episode (video). The value is a dict mapping frame IDs to per-frame annotation data:

{
    0: {  # frame_id
        "time_clip": [[0, 132], [132, 197], [198, 224]],  # temporal segment boundaries
        "instruction_add": "make a burger",                 # language instruction
        "substask": "pick up the burger",                   # subtask description
        "primitive_skill": "pick",                          # primitive skill label
        "segmentation": None,                               # reserved, not stored yet
        "object_box": [[x1, y1], [x2, y2]],                # object bounding box
        "placement_proposal": [[x1, y1], [x2, y2]],        # placement proposal box
        "trace": [[x, y], ...],                             # motion trace (next 10 steps)
        "gripper_box": [[x1, y1], [x2, y2]],               # gripper bounding box
        "contact_frame": 101,                               # contact frame index (-1 if past)
        "state_affordance": [x, y, z, rx, ry, rz],         # ee pose at contact frame
        "affordance_box": [[x1, y1], [x2, y2]],            # gripper box at contact frame
        "contact_points": [x, y],                           # contact point coordinates
    },
    1: {...},
    ...
}

---

convert_pkl_to_lmdb.py

Converts merged DROID and RH20T annotation pkl files into a single frame-level LMDB database.

Input

• droid_annotation.pkl -- DROID pkl containing intermediate representations and language data
• rh20t_annotation.pkl -- RH20T pkl containing intermediate representations and language data

Usage

python convert_pkl_to_lmdb.py \
    --droid_pkl /path/to/droid_annotation.pkl \
    --rh20t_pkl /path/to/rh20t_annotation.pkl \
    --output_lmdb /path/to/output_lmdb \
    --data_lmdb_path /path/to/episode_directories/

Arguments

Argument	Description	Default
--droid_pkl	Path to the merged DROID annotation pkl	Required
--rh20t_pkl	Path to the merged RH20T annotation pkl	Required
--output_lmdb	Output LMDB path	Required
--data_lmdb_path	Path to action dataset episode directories (for reading meta_info.pkl)	Required
--map_size	LMDB map size in bytes	100 GB
--dry_run	Debug mode: process without writing, print statistics and samples	False

---

read_lmdb.py

Reads and validates LMDB files generated by convert_pkl_to_lmdb.py. Provides multiple inspection actions.

Usage

# Show basic LMDB info (total entries, DROID/RH20T counts)
python read_lmdb.py --lmdb_path /path/to/lmdb --action info

# List keys
python read_lmdb.py --lmdb_path /path/to/lmdb --action keys --limit 20

# Inspect a single item (show structure and sample frame)
python read_lmdb.py --lmdb_path /path/to/lmdb --action item --key <video_id> --sample_frame 0

# Show per-field coverage statistics for a single item
python read_lmdb.py --lmdb_path /path/to/lmdb --action stats --key <video_id>

# Aggregate summary across multiple items
python read_lmdb.py --lmdb_path /path/to/lmdb --action summary --limit 100

Actions

Action	Description
info	Print basic LMDB info: total entries, DROID/RH20T counts, sample keys
keys	List LMDB keys (up to --limit)
item	Display structure and sample frame data for a single item
stats	Per-frame field coverage statistics for a single item (valid / None / empty)
summary	Aggregate statistics across multiple items: average frame count, language coverage, field coverage

---

Dependencies

• Python 3.8+
• lmdb
• numpy
• tqdm (for convert_pkl_to_lmdb.py)