pymcap-cli 0.12.0__tar.gz → 0.13.0__tar.gz

{pymcap_cli-0.12.0 → pymcap_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pymcap-cli
-Version: 0.12.0
+Version: 0.13.0
 Summary: High-performance Python CLI for MCAP file processing with advanced recovery, filtering, and optimization capabilities
 Keywords: mcap,cli,robotics,ros,ros2,recovery,filtering,compression
 Author: Marko Bausch
@@ -76,8 +76,14 @@ uvx pymcap-cli info data.mcap
 # Or add to your project
 uv add pymcap-cli
 
-# With video support (for video and roscompress commands)
-uv add pymcap-cli[video]
+# With video support (for video generation and ROS image compression)
+uv add "pymcap-cli[video]"
+
+# With ROS image and point-cloud compression support
+uv add "pymcap-cli[video,pointcloud]"
+
+# Add Draco point-cloud compression support
+uv add "pymcap-cli[video,pointcloud,draco]"
 ```
 
 ## Why pymcap-cli over the official Go CLI?
@@ -158,6 +164,16 @@ pymcap-cli cat recording.mcap --bytes base64   # base64-encoded
 pymcap-cli cat recording.mcap --bytes skip     # omit binary fields
 ```
 
+### `doctor` — MCAP Container Validation
+
+Check an MCAP file structure against the MCAP container specification, with
+summary, index, chunk, message-order, and advisory findings.
+
+```bash
+pymcap-cli doctor data.mcap
+pymcap-cli doctor data.mcap --strict-message-order --show-all
+```
+
 ### `tftree` — TF Transform Tree
 
 Visualize the ROS TF transform tree with colored static/dynamic transforms, translation and rotation values.
@@ -176,6 +192,16 @@ pymcap-cli tftree data.mcap
 pymcap-cli tftree data.mcap --static-only
 ```
 
+### `tf-get` — TF Transform Lookup
+
+Resolve the transform from a source frame into a target frame using `/tf_static`
+and `/tf`. Without `--at`, dynamic edges use their latest sample.
+
+```bash
+pymcap-cli tf-get data.mcap map base_link
+pymcap-cli tf-get data.mcap odom base_link --at 2024-01-01T10:00:00Z
+```
+
 ### `tf-export` — TF Tree to URDF / SDF / JSON
 
 Reconstruct robot description files from `/tf_static` (and optionally `/tf` at a
@@ -376,7 +402,7 @@ Filter messages by topic patterns (simpler version of `process`).
 
 ```bash
 # Include specific topics
-pymcap-cli filter data.mcap -o filtered.mcap --include-topics "/camera/image" "/lidar/points"
+pymcap-cli filter data.mcap -o filtered.mcap --topics "/camera/image" "/lidar/points"
 
 # Exclude topics
 pymcap-cli filter data.mcap -o filtered.mcap --exclude-topics "/debug.*" "/test.*"
@@ -407,10 +433,32 @@ List various record types in an MCAP file.
 pymcap-cli list channels data.mcap
 pymcap-cli list chunks data.mcap
 pymcap-cli list schemas data.mcap
+pymcap-cli list schema data.mcap --name sensor_msgs/msg/Image
 pymcap-cli list attachments data.mcap
 pymcap-cli list metadata data.mcap
 ```
 
+### `msg` — ROS2 Message Definitions
+
+Resolve, list, and browse ROS2 `.msg` definitions. `msg def` prints complete
+definitions including dependencies; `msg list` lists package message types; and
+`msg serve` starts a local browser UI.
+
+```bash
+# Resolve a standard ROS2 message
+pymcap-cli msg def sensor_msgs/msg/Image --distro humble
+
+# Include custom package roots before AMENT_PREFIX_PATH and the user cache
+pymcap-cli msg def my_robot_msgs/msg/Status -I ./install/share
+
+# List messages in a package or browse definitions locally
+pymcap-cli msg list sensor_msgs --distro jazzy
+pymcap-cli msg serve --distro jazzy --no-browser
+```
+
+Missing standard packages are resolved from rosdistro/GitHub and cached under
+the `pymcap_cli_msg_def` user cache.
+
 ### `get` — Extract Attachments and Metadata
 
 Extract a single attachment's bytes or a metadata record's key/value map.
@@ -460,6 +508,24 @@ pymcap-cli duplicates /data/recordings --all
 pymcap-cli duplicates /data/recordings --rebuild-missing
 ```
 
+### `index` — Sidecar Catalog
+
+Maintain a sidecar SQLite catalog of MCAP summaries for fast lookup across
+large recording trees. Requires the `xxhash` extra.
+
+```bash
+# Scan a tree and skip unchanged files on later runs
+pymcap-cli index scan /data/recordings
+
+# Coverage and directory-level rollups
+pymcap-cli index status /data/recordings
+pymcap-cli index tree /data/recordings --max-depth 3
+
+# Query by topic/schema/time and inspect catalog-wide topics
+pymcap-cli index query /data/recordings --topic /camera/front --format json
+pymcap-cli index topics /camera --sort-by messages
+```
+
 ### `records` — Raw Record Dump
 
 Print every MCAP record in file order using its `repr`. Useful for inspecting
@@ -480,22 +546,26 @@ pymcap-cli topic-chunks data.mcap
 
 ### `video` — Video Generation
 
-Generate MP4 videos from image topics using hardware-accelerated encoding. Requires the `video` extra.
+Generate one MP4 per image topic using hardware-accelerated encoding. Requires
+the `video` extra.
 
 ```bash
 # Basic video generation
-pymcap-cli video data.mcap --topic /camera/front --output front.mp4
+pymcap-cli video data.mcap --topic /camera/front --output ./videos
 
 # With quality preset
-pymcap-cli video data.mcap --topic /camera/rear --output rear.mp4 --quality high
+pymcap-cli video data.mcap --topic /camera/rear --output ./videos --quality high
 
 # Use specific codec and encoder
-pymcap-cli video data.mcap --topic /lidar/image --output lidar.mp4 --codec h265 --encoder videotoolbox
+pymcap-cli video data.mcap --topic /lidar/image --output ./videos --codec h265 --encoder videotoolbox
 ```
 
-### `roscompress` — ROS Image Compression
+### `roscompress` — ROS Image and Point-Cloud Compression
 
-Compress ROS MCAP files by converting CompressedImage/Image topics to CompressedVideo format and PointCloud2 topics to Cloudini or Draco compressed point clouds.
+Compress ROS MCAP files by converting CompressedImage/Image topics to
+CompressedVideo format and PointCloud2 topics to Cloudini or Draco compressed
+point clouds. Requires the `video` and `pointcloud` extras; Draco compression
+also requires the `draco` extra.
 
 ```bash
 # Basic compression
@@ -510,7 +580,7 @@ pymcap-cli roscompress data.mcap -o compressed.mcap --pc-format draco --pc-schem
 
 ### `rosdecompress` — ROS Decompression
 
-Decompress CompressedVideo, CompressedPointCloud2, and Foxglove CompressedPointCloud topics back to standard ROS formats.
+Decompress CompressedVideo, CompressedPointCloud2, and Foxglove CompressedPointCloud topics back to standard ROS formats. Requires the `video` and `pointcloud` extras.
 
 ```bash
 # Decompress to CompressedImage (JPEG)
@@ -605,6 +675,22 @@ pymcap-cli export-geo data.mcap -o ./geo --format gpx --mode track --stride 5
 pymcap-cli export-geo data.mcap -o ./geo --include-no-fix
 ```
 
+### `bridge` — Live Foxglove Bridge
+
+Inspect, stream, or record live topics from a Foxglove WebSocket bridge. Requires
+the `bridge` extra.
+
+```bash
+# Inspect advertised channels
+pymcap-cli bridge localhost:8765
+
+# Stream decoded messages
+pymcap-cli bridge cat localhost:8765 --topics /tf --limit 10
+
+# Record all advertised topics to MCAP
+pymcap-cli bridge record localhost:8765 --all -o live.mcap
+```
+
 ### Shell Autocompletion
 
 ```bash
@@ -631,9 +717,9 @@ pymcap-cli process full_log.mcap -o camera.mcap \
 # Recover corrupt file and compress in one pass
 pymcap-cli process corrupt.mcap -o recovered.mcap --recovery-mode --compression lz4
 
-# Fast filtering with chunk copying (up to 10x faster)
+# Fast filtering with automatic chunk copying when possible
 pymcap-cli process 100gb_file.mcap -o filtered.mcap \
-  -y "/lidar.*" --chunk-copying --compression zstd
+  -y "/lidar.*" --compression zstd
 
 # Optimize for topic-specific playback
 pymcap-cli rechunk robot_log.mcap -o optimized.mcap \
@@ -653,14 +739,14 @@ pymcap-cli rechunk robot_log.mcap -o optimized.mcap \
 
 ```bash
 # Setup development environment
-uv sync
+uv sync --all-groups --all-extras --all-packages
 
 # Run locally during development
 uv run pymcap-cli --help
 
 # Format and lint code
-uv run pre-commit run --all-files
+pre-commit run --all-files
 
 # Run tests
-uv run pytest pymcap-cli/tests
+uv run pytest pymcap-cli/tests -m "not benchmark" --no-cov -q
 ```

{pymcap_cli-0.12.0 → pymcap_cli-0.13.0}/README.md

@@ -17,8 +17,14 @@ uvx pymcap-cli info data.mcap
 # Or add to your project
 uv add pymcap-cli
 
-# With video support (for video and roscompress commands)
-uv add pymcap-cli[video]
+# With video support (for video generation and ROS image compression)
+uv add "pymcap-cli[video]"
+
+# With ROS image and point-cloud compression support
+uv add "pymcap-cli[video,pointcloud]"
+
+# Add Draco point-cloud compression support
+uv add "pymcap-cli[video,pointcloud,draco]"
 ```
 
 ## Why pymcap-cli over the official Go CLI?
@@ -99,6 +105,16 @@ pymcap-cli cat recording.mcap --bytes base64   # base64-encoded
 pymcap-cli cat recording.mcap --bytes skip     # omit binary fields
 ```
 
+### `doctor` — MCAP Container Validation
+
+Check an MCAP file structure against the MCAP container specification, with
+summary, index, chunk, message-order, and advisory findings.
+
+```bash
+pymcap-cli doctor data.mcap
+pymcap-cli doctor data.mcap --strict-message-order --show-all
+```
+
 ### `tftree` — TF Transform Tree
 
 Visualize the ROS TF transform tree with colored static/dynamic transforms, translation and rotation values.
@@ -117,6 +133,16 @@ pymcap-cli tftree data.mcap
 pymcap-cli tftree data.mcap --static-only
 ```
 
+### `tf-get` — TF Transform Lookup
+
+Resolve the transform from a source frame into a target frame using `/tf_static`
+and `/tf`. Without `--at`, dynamic edges use their latest sample.
+
+```bash
+pymcap-cli tf-get data.mcap map base_link
+pymcap-cli tf-get data.mcap odom base_link --at 2024-01-01T10:00:00Z
+```
+
 ### `tf-export` — TF Tree to URDF / SDF / JSON
 
 Reconstruct robot description files from `/tf_static` (and optionally `/tf` at a
@@ -317,7 +343,7 @@ Filter messages by topic patterns (simpler version of `process`).
 
 ```bash
 # Include specific topics
-pymcap-cli filter data.mcap -o filtered.mcap --include-topics "/camera/image" "/lidar/points"
+pymcap-cli filter data.mcap -o filtered.mcap --topics "/camera/image" "/lidar/points"
 
 # Exclude topics
 pymcap-cli filter data.mcap -o filtered.mcap --exclude-topics "/debug.*" "/test.*"
@@ -348,10 +374,32 @@ List various record types in an MCAP file.
 pymcap-cli list channels data.mcap
 pymcap-cli list chunks data.mcap
 pymcap-cli list schemas data.mcap
+pymcap-cli list schema data.mcap --name sensor_msgs/msg/Image
 pymcap-cli list attachments data.mcap
 pymcap-cli list metadata data.mcap
 ```
 
+### `msg` — ROS2 Message Definitions
+
+Resolve, list, and browse ROS2 `.msg` definitions. `msg def` prints complete
+definitions including dependencies; `msg list` lists package message types; and
+`msg serve` starts a local browser UI.
+
+```bash
+# Resolve a standard ROS2 message
+pymcap-cli msg def sensor_msgs/msg/Image --distro humble
+
+# Include custom package roots before AMENT_PREFIX_PATH and the user cache
+pymcap-cli msg def my_robot_msgs/msg/Status -I ./install/share
+
+# List messages in a package or browse definitions locally
+pymcap-cli msg list sensor_msgs --distro jazzy
+pymcap-cli msg serve --distro jazzy --no-browser
+```
+
+Missing standard packages are resolved from rosdistro/GitHub and cached under
+the `pymcap_cli_msg_def` user cache.
+
 ### `get` — Extract Attachments and Metadata
 
 Extract a single attachment's bytes or a metadata record's key/value map.
@@ -401,6 +449,24 @@ pymcap-cli duplicates /data/recordings --all
 pymcap-cli duplicates /data/recordings --rebuild-missing
 ```
 
+### `index` — Sidecar Catalog
+
+Maintain a sidecar SQLite catalog of MCAP summaries for fast lookup across
+large recording trees. Requires the `xxhash` extra.
+
+```bash
+# Scan a tree and skip unchanged files on later runs
+pymcap-cli index scan /data/recordings
+
+# Coverage and directory-level rollups
+pymcap-cli index status /data/recordings
+pymcap-cli index tree /data/recordings --max-depth 3
+
+# Query by topic/schema/time and inspect catalog-wide topics
+pymcap-cli index query /data/recordings --topic /camera/front --format json
+pymcap-cli index topics /camera --sort-by messages
+```
+
 ### `records` — Raw Record Dump
 
 Print every MCAP record in file order using its `repr`. Useful for inspecting
@@ -421,22 +487,26 @@ pymcap-cli topic-chunks data.mcap
 
 ### `video` — Video Generation
 
-Generate MP4 videos from image topics using hardware-accelerated encoding. Requires the `video` extra.
+Generate one MP4 per image topic using hardware-accelerated encoding. Requires
+the `video` extra.
 
 ```bash
 # Basic video generation
-pymcap-cli video data.mcap --topic /camera/front --output front.mp4
+pymcap-cli video data.mcap --topic /camera/front --output ./videos
 
 # With quality preset
-pymcap-cli video data.mcap --topic /camera/rear --output rear.mp4 --quality high
+pymcap-cli video data.mcap --topic /camera/rear --output ./videos --quality high
 
 # Use specific codec and encoder
-pymcap-cli video data.mcap --topic /lidar/image --output lidar.mp4 --codec h265 --encoder videotoolbox
+pymcap-cli video data.mcap --topic /lidar/image --output ./videos --codec h265 --encoder videotoolbox
 ```
 
-### `roscompress` — ROS Image Compression
+### `roscompress` — ROS Image and Point-Cloud Compression
 
-Compress ROS MCAP files by converting CompressedImage/Image topics to CompressedVideo format and PointCloud2 topics to Cloudini or Draco compressed point clouds.
+Compress ROS MCAP files by converting CompressedImage/Image topics to
+CompressedVideo format and PointCloud2 topics to Cloudini or Draco compressed
+point clouds. Requires the `video` and `pointcloud` extras; Draco compression
+also requires the `draco` extra.
 
 ```bash
 # Basic compression
@@ -451,7 +521,7 @@ pymcap-cli roscompress data.mcap -o compressed.mcap --pc-format draco --pc-schem
 
 ### `rosdecompress` — ROS Decompression
 
-Decompress CompressedVideo, CompressedPointCloud2, and Foxglove CompressedPointCloud topics back to standard ROS formats.
+Decompress CompressedVideo, CompressedPointCloud2, and Foxglove CompressedPointCloud topics back to standard ROS formats. Requires the `video` and `pointcloud` extras.
 
 ```bash
 # Decompress to CompressedImage (JPEG)
@@ -546,6 +616,22 @@ pymcap-cli export-geo data.mcap -o ./geo --format gpx --mode track --stride 5
 pymcap-cli export-geo data.mcap -o ./geo --include-no-fix
 ```
 
+### `bridge` — Live Foxglove Bridge
+
+Inspect, stream, or record live topics from a Foxglove WebSocket bridge. Requires
+the `bridge` extra.
+
+```bash
+# Inspect advertised channels
+pymcap-cli bridge localhost:8765
+
+# Stream decoded messages
+pymcap-cli bridge cat localhost:8765 --topics /tf --limit 10
+
+# Record all advertised topics to MCAP
+pymcap-cli bridge record localhost:8765 --all -o live.mcap
+```
+
 ### Shell Autocompletion
 
 ```bash
@@ -572,9 +658,9 @@ pymcap-cli process full_log.mcap -o camera.mcap \
 # Recover corrupt file and compress in one pass
 pymcap-cli process corrupt.mcap -o recovered.mcap --recovery-mode --compression lz4
 
-# Fast filtering with chunk copying (up to 10x faster)
+# Fast filtering with automatic chunk copying when possible
 pymcap-cli process 100gb_file.mcap -o filtered.mcap \
-  -y "/lidar.*" --chunk-copying --compression zstd
+  -y "/lidar.*" --compression zstd
 
 # Optimize for topic-specific playback
 pymcap-cli rechunk robot_log.mcap -o optimized.mcap \
@@ -594,14 +680,14 @@ pymcap-cli rechunk robot_log.mcap -o optimized.mcap \
 
 ```bash
 # Setup development environment
-uv sync
+uv sync --all-groups --all-extras --all-packages
 
 # Run locally during development
 uv run pymcap-cli --help
 
 # Format and lint code
-uv run pre-commit run --all-files
+pre-commit run --all-files
 
 # Run tests
-uv run pytest pymcap-cli/tests
+uv run pytest pymcap-cli/tests -m "not benchmark" --no-cov -q
 ```

{pymcap_cli-0.12.0 → pymcap_cli-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pymcap-cli"
-version = "0.12.0"
+version = "0.13.0"
 description = "High-performance Python CLI for MCAP file processing with advanced recovery, filtering, and optimization capabilities"
 readme = "README.md"
 requires-python = ">=3.10"

{pymcap_cli-0.12.0 → pymcap_cli-0.13.0}/src/pymcap_cli/cli.py

@@ -37,6 +37,7 @@ from pymcap_cli.cmd import (
     tftree_cmd,
     topic_chunks_cmd,
 )
+from pymcap_cli.cmd import msg as msg_pkg
 from pymcap_cli.log_setup import ERR, setup_logging
 
 CommandFunction: TypeAlias = Callable[..., int]
@@ -194,7 +195,7 @@ rosdecompress = _load_optional_command(
     install_command="uv add 'pymcap-cli[video,pointcloud]'",
 )
 index_app = _load_optional_app(
-    "pymcap_cli.cmd.index_cmd",
+    "pymcap_cli.cmd.index",
     "index_app",
     expected_missing_modules=("xxhash",),
     message="Index command requires the 'xxhash' extra "
@@ -225,6 +226,8 @@ app.command(name="diff", group=inspect_group)(diff_cmd.diff_cmd)
 app.command(name="duplicates", group=inspect_group)(duplicates_cmd.duplicates)
 app.command(name="info", group=inspect_group)(info_cmd.info)
 app.command(name="info-json", group=inspect_group)(info_json_cmd.info_json)
+msg_pkg.msg_app.group = (inspect_group,)
+app.command(msg_pkg.msg_app, name="msg")
 index_app.group = (inspect_group,)
 app.command(index_app, name="index")
 get_cmd.get_app.group = (inspect_group,)

pymcap_cli-0.13.0/src/pymcap_cli/cmd/index/__init__.py

@@ -0,0 +1,41 @@
+"""``pymcap-cli index`` — sidecar catalog of MCAP summaries.
+
+Each subcommand lives in its own module; this file is just the
+cyclopts assembler. Shared helpers and constants live in
+:mod:`pymcap_cli.cmd.index._helpers`.
+"""
+
+import logging
+
+from cyclopts import App
+
+from pymcap_cli.cmd.index.duplicates_cmd import duplicates_cmd
+from pymcap_cli.cmd.index.errors_cmd import errors_cmd
+from pymcap_cli.cmd.index.info_cmd import info_cmd
+from pymcap_cli.cmd.index.query_cmd import query_cmd
+from pymcap_cli.cmd.index.scan_cmd import scan_cmd
+from pymcap_cli.cmd.index.schemas_cmd import schemas_cmd
+from pymcap_cli.cmd.index.sessions_cmd import sessions_cmd
+from pymcap_cli.cmd.index.status_cmd import status_cmd
+from pymcap_cli.cmd.index.timeline_cmd import timeline_cmd
+from pymcap_cli.cmd.index.topics_cmd import topics_cmd
+from pymcap_cli.cmd.index.tree_cmd import tree_cmd
+
+logger = logging.getLogger(__name__)
+
+index_app = App(
+    name="index",
+    help="Maintain a sidecar SQLite catalog of MCAP summaries for fast recovery.",
+)
+
+index_app.command(scan_cmd, name="scan")
+index_app.command(status_cmd, name="status")
+index_app.command(tree_cmd, name="tree")
+index_app.command(query_cmd, name="query")
+index_app.command(topics_cmd, name="topics")
+index_app.command(schemas_cmd, name="schemas")
+index_app.command(duplicates_cmd, name="duplicates")
+index_app.command(sessions_cmd, name="sessions")
+index_app.command(errors_cmd, name="errors")
+index_app.command(timeline_cmd, name="timeline")
+index_app.command(info_cmd, name="info")