mcap2img 0.1.0__py3-none-any.whl

mcap2img/__init__.py

@@ -0,0 +1,3 @@
+"""Convert MCAP camera frames to PNG with robot coordinate axis overlays."""
+
+__version__ = "0.1.0"

mcap2img/__main__.py

@@ -0,0 +1,4 @@
+from mcap2img.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcap2img/cli.py

@@ -0,0 +1,246 @@
+"""CLI entry point for mcap2img."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+import cv2
+
+from mcap2img.overlay import draw_robot_axes_overlay
+from mcap2img.progress import ProgressReporter
+from mcap2img.reader import CAMERA_HOST_ROBOT_ID, McapReader
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_camera_ids(raw: str) -> list[int]:
+    ids = [int(x.strip()) for x in raw.split(",") if x.strip()]
+    if not ids:
+        raise ValueError("At least one camera id is required")
+    return ids
+
+
+def _parse_robot_ids(raw: str) -> list[str]:
+    ids = [x.strip() for x in raw.split(",") if x.strip()]
+    if not ids:
+        raise ValueError("At least one overlay robot id is required")
+    return ids
+
+
+def _resolve_mcap_inputs(input_path: Path) -> tuple[list[Path], bool]:
+    """Return MCAP file list and whether input is a batch directory."""
+    if input_path.is_file():
+        return [input_path], False
+    if input_path.is_dir():
+        files = sorted(input_path.glob("*.mcap"))
+        return files, True
+    return [], False
+
+
+def _output_dir_for_mcap(base_output: Path, mcap_path: Path, *, batch: bool) -> Path:
+    if batch:
+        return base_output / mcap_path.stem
+    return base_output
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Export MCAP camera frames to PNG with robot axis overlays.",
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        help="Path to a local .mcap file, or a directory of .mcap files for batch export",
+    )
+    parser.add_argument("--output", default="./output", help="Output directory")
+    parser.add_argument(
+        "--cameras",
+        default="2",
+        help="Comma-separated camera indices (default: 2)",
+    )
+    parser.add_argument(
+        "--overlay-robots",
+        default="robot1,robot2",
+        help="Comma-separated robot ids for axis overlay (default: robot1,robot2)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    return parser
+
+
+def run(
+    input_path: Path,
+    output_dir: Path,
+    camera_ids: list[int],
+    overlay_robot_ids: list[str],
+    *,
+    batch: bool = False,
+) -> int:
+    if not input_path.is_file():
+        logger.error("Input file not found: %s", input_path)
+        return 1
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for cam_id in camera_ids:
+        (output_dir / f"camera{cam_id}").mkdir(parents=True, exist_ok=True)
+
+    reader = McapReader(
+        mcap_path=input_path,
+        camera_ids=camera_ids,
+        overlay_robot_ids=overlay_robot_ids,
+    )
+    logger.info("Scanning %s ...", input_path)
+    scan = reader.scan_and_decode()
+
+    stats = {
+        "frames_saved": 0,
+        "overlay_drawn": 0,
+        "overlay_skipped": 0,
+        "missing_calib": 0,
+    }
+
+    cam_host_index = scan.robot_pose_index.get(CAMERA_HOST_ROBOT_ID)
+
+    total_frames = sum(len(scan.camera_frames.get(cam_id, [])) for cam_id in camera_ids)
+    export_progress = ProgressReporter("Exporting PNG", total_frames)
+    logger.info("Exporting %d frames across %d cameras ...", total_frames, len(camera_ids))
+
+    for cam_id in camera_ids:
+        frames = scan.camera_frames.get(cam_id, [])
+        info_index = scan.camera_info_index.get(cam_id)
+
+        for ts_ns, image in frames:
+            out_path = output_dir / f"camera{cam_id}" / f"{ts_ns}.png"
+            frame = image.copy()
+
+            camera_info = info_index.nearest(ts_ns) if info_index else None
+            cam_robot_info = cam_host_index.nearest(ts_ns) if cam_host_index else None
+
+            overlay_robots = []
+            for rid in overlay_robot_ids:
+                idx = scan.robot_pose_index.get(rid)
+                if idx is not None:
+                    overlay_robots.append((rid, idx.nearest(ts_ns)))
+
+            if camera_info is None or cam_robot_info is None:
+                stats["missing_calib"] += 1
+                stats["overlay_skipped"] += 1
+            else:
+                drew = draw_robot_axes_overlay(
+                    frame,
+                    camera_info,
+                    cam_robot_info,
+                    overlay_robots,
+                )
+                if drew:
+                    stats["overlay_drawn"] += 1
+                else:
+                    stats["overlay_skipped"] += 1
+
+            if not cv2.imwrite(str(out_path), frame):
+                logger.error("Failed to write %s", out_path)
+                return 1
+            stats["frames_saved"] += 1
+            export_progress.advance()
+
+    export_progress.finish()
+
+    logger.info(
+        "Done: saved=%d overlay_drawn=%d overlay_skipped=%d missing_calib=%d",
+        stats["frames_saved"],
+        stats["overlay_drawn"],
+        stats["overlay_skipped"],
+        stats["missing_calib"],
+    )
+    for cam_id in camera_ids:
+        n = len(scan.camera_frames.get(cam_id, []))
+        logger.info("  camera%d: %d frames -> %s", cam_id, n, output_dir / f"camera{cam_id}")
+    return 0
+
+
+def run_batch(
+    input_dir: Path,
+    output_dir: Path,
+    camera_ids: list[int],
+    overlay_robot_ids: list[str],
+) -> int:
+    mcap_files, batch = _resolve_mcap_inputs(input_dir)
+    if not mcap_files:
+        logger.error("No .mcap files found in: %s", input_dir)
+        return 1
+
+    logger.info("Batch mode: %d MCAP file(s) in %s", len(mcap_files), input_dir)
+    exit_code = 0
+    for index, mcap_path in enumerate(mcap_files, start=1):
+        logger.info(
+            "Processing [%d/%d] %s",
+            index,
+            len(mcap_files),
+            mcap_path.name,
+        )
+        per_file_output = _output_dir_for_mcap(output_dir, mcap_path, batch=batch)
+        code = run(
+            input_path=mcap_path,
+            output_dir=per_file_output,
+            camera_ids=camera_ids,
+            overlay_robot_ids=overlay_robot_ids,
+            batch=batch,
+        )
+        if code != 0:
+            exit_code = code
+    return exit_code
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_arg_parser()
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(levelname)s: %(message)s",
+    )
+
+    try:
+        camera_ids = _parse_camera_ids(args.cameras)
+        overlay_robot_ids = _parse_robot_ids(args.overlay_robots)
+    except ValueError as exc:
+        logger.error("%s", exc)
+        return 2
+
+    input_path = Path(args.input)
+    mcap_files, batch = _resolve_mcap_inputs(input_path)
+    if not mcap_files:
+        if input_path.is_file():
+            logger.error("Input file not found: %s", input_path)
+        elif input_path.is_dir():
+            logger.error("No .mcap files found in: %s", input_path)
+        else:
+            logger.error("Input path not found: %s", input_path)
+        return 1
+
+    if batch:
+        return run_batch(
+            input_dir=input_path,
+            output_dir=Path(args.output),
+            camera_ids=camera_ids,
+            overlay_robot_ids=overlay_robot_ids,
+        )
+
+    return run(
+        input_path=mcap_files[0],
+        output_dir=Path(args.output),
+        camera_ids=camera_ids,
+        overlay_robot_ids=overlay_robot_ids,
+        batch=False,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcap2img/overlay.py

@@ -0,0 +1,100 @@
+"""Draw projected robot coordinate axes on images."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import cv2
+import numpy as np
+
+from mcap2img.projection import (
+    AxisSegment,
+    build_world_to_camera_optical,
+    project_robot_axes,
+    resolve_intrinsics_mode,
+    robot_info_has_projectable_base_link,
+)
+
+
+def _hex_to_bgr(hex_color: str) -> tuple[int, int, int]:
+    hex_color = hex_color.lstrip("#")
+    r = int(hex_color[0:2], 16)
+    g = int(hex_color[2:4], 16)
+    b = int(hex_color[4:6], 16)
+    return b, g, r
+
+
+LABEL_FILL_BGR = _hex_to_bgr("#f8f8f8")
+
+
+def draw_axis_segments(
+    image: np.ndarray,
+    segments: list[AxisSegment],
+    robot_id: str,
+) -> None:
+    if not segments:
+        return
+
+    origin_uv = segments[0].origin_uv
+    ox, oy = int(round(origin_uv[0])), int(round(origin_uv[1]))
+
+    for seg in segments:
+        tx, ty = int(round(seg.tip_uv[0])), int(round(seg.tip_uv[1]))
+        cv2.line(image, (ox, oy), (tx, ty), seg.color_bgr, 4, cv2.LINE_AA)
+        cv2.putText(
+            image,
+            seg.tag.lower(),
+            (tx + 4, ty + 14),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            0.55,
+            seg.color_bgr,
+            2,
+            cv2.LINE_AA,
+        )
+
+    cv2.putText(
+        image,
+        robot_id,
+        (ox, oy + 22),
+        cv2.FONT_HERSHEY_SIMPLEX,
+        0.55,
+        LABEL_FILL_BGR,
+        2,
+        cv2.LINE_AA,
+    )
+
+
+def draw_robot_axes_overlay(
+    image: np.ndarray,
+    camera_info: Any,
+    cam_robot_info: Any,
+    overlay_robots: list[tuple[str, Any]],
+) -> bool:
+    """Draw axes for overlay robots. Returns True if any axes were drawn."""
+    if camera_info is None or cam_robot_info is None:
+        return False
+    if resolve_intrinsics_mode(camera_info) is None:
+        return False
+    if not robot_info_has_projectable_base_link(cam_robot_info):
+        return False
+
+    world_to_camera = build_world_to_camera_optical(camera_info, cam_robot_info)
+    if world_to_camera is None:
+        return False
+
+    img_h, img_w = image.shape[:2]
+    drew_any = False
+    for robot_id, robot_info in overlay_robots:
+        if not robot_info_has_projectable_base_link(robot_info):
+            continue
+        segments = project_robot_axes(
+            camera_info,
+            world_to_camera,
+            robot_info,
+            img_w,
+            img_h,
+        )
+        if segments:
+            draw_axis_segments(image, segments, robot_id)
+            drew_any = True
+    return drew_any

mcap2img/pb/CameraCalibration_pb2.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: CameraCalibration.proto
+# Protobuf Python Version: 4.25.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x17\x43\x61meraCalibration.proto\x12\x08\x66oxglove\"|\n\x11\x43\x61meraCalibration\x12\r\n\x05width\x18\x02 \x01(\x07\x12\x0e\n\x06height\x18\x03 \x01(\x07\x12\x18\n\x10\x64istortion_model\x18\x04 \x01(\t\x12\t\n\x01\x44\x18\x05 \x03(\x01\x12\t\n\x01K\x18\x06 \x03(\x01\x12\t\n\x01P\x18\x08 \x03(\x01\x12\r\n\x05T_b_c\x18\n \x03(\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'CameraCalibration_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_CAMERACALIBRATION']._serialized_start=37
+  _globals['_CAMERACALIBRATION']._serialized_end=161
+# @@protoc_insertion_point(module_scope)

mcap2img/pb/CompressedImage_pb2.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: CompressedImage.proto
+# Protobuf Python Version: 4.25.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x15\x43ompressedImage.proto\x12\x08\x66oxglove\"/\n\x0f\x43ompressedImage\x12\x0c\n\x04\x64\x61ta\x18\x02 \x01(\x0c\x12\x0e\n\x06\x66ormat\x18\x03 \x01(\tb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'CompressedImage_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_COMPRESSEDIMAGE']._serialized_start=35
+  _globals['_COMPRESSEDIMAGE']._serialized_end=82
+# @@protoc_insertion_point(module_scope)

mcap2img/pb/Pose_pb2.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: Pose.proto
+# Protobuf Python Version: 4.25.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from mcap2img.pb import Quaternion_pb2 as Quaternion__pb2
+from mcap2img.pb import Vector3_pb2 as Vector3__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\nPose.proto\x12\x08\x66oxglove\x1a\x10Quaternion.proto\x1a\rVector3.proto\"V\n\x04Pose\x12#\n\x08position\x18\x01 \x01(\x0b\x32\x11.foxglove.Vector3\x12)\n\x0borientation\x18\x02 \x01(\x0b\x32\x14.foxglove.Quaternionb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'Pose_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_POSE']._serialized_start=57
+  _globals['_POSE']._serialized_end=143
+# @@protoc_insertion_point(module_scope)

mcap2img/pb/Quaternion_pb2.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: Quaternion.proto
+# Protobuf Python Version: 4.25.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x10Quaternion.proto\x12\x08\x66oxglove\"8\n\nQuaternion\x12\t\n\x01x\x18\x01 \x01(\x01\x12\t\n\x01y\x18\x02 \x01(\x01\x12\t\n\x01z\x18\x03 \x01(\x01\x12\t\n\x01w\x18\x04 \x01(\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'Quaternion_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_QUATERNION']._serialized_start=30
+  _globals['_QUATERNION']._serialized_end=86
+# @@protoc_insertion_point(module_scope)

mcap2img/pb/RobotInfo_pb2.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: RobotInfo.proto
+# Protobuf Python Version: 4.25.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from mcap2img.pb import Pose_pb2 as Pose__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0fRobotInfo.proto\x12\x08\x66oxglove\x1a\nPose.proto\"@\n\rRobotLinkInfo\x12\x0c\n\x04name\x18\x01 \x01(\t\x12!\n\ttransform\x18\x02 \x01(\x0b\x32\x0e.foxglove.Pose\"f\n\tRobotInfo\x12*\n\tbase_link\x18\x08 \x01(\x0b\x32\x17.foxglove.RobotLinkInfo\x12-\n\rbaselink_type\x18\t \x01(\x0e\x32\x16.foxglove.BaselinkType*\\\n\x0c\x42\x61selinkType\x12\x1d\n\x19\x42\x41SELINK_TYPE_UNSPECIFIED\x10\x00\x12\x18\n\x14USE_BASELINK_AS_POSE\x10\x01\x12\x13\n\x0fIGNORE_BASELINK\x10\x02\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'RobotInfo_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_BASELINKTYPE']._serialized_start=211
+  _globals['_BASELINKTYPE']._serialized_end=303
+  _globals['_ROBOTLINKINFO']._serialized_start=41
+  _globals['_ROBOTLINKINFO']._serialized_end=105
+  _globals['_ROBOTINFO']._serialized_start=107
+  _globals['_ROBOTINFO']._serialized_end=209
+# @@protoc_insertion_point(module_scope)

mcap2img/pb/Vector3_pb2.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: Vector3.proto
+# Protobuf Python Version: 4.25.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\rVector3.proto\x12\x08\x66oxglove\"*\n\x07Vector3\x12\t\n\x01x\x18\x01 \x01(\x01\x12\t\n\x01y\x18\x02 \x01(\x01\x12\t\n\x01z\x18\x03 \x01(\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'Vector3_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_VECTOR3']._serialized_start=27
+  _globals['_VECTOR3']._serialized_end=69
+# @@protoc_insertion_point(module_scope)

mcap2img/pb/__init__.py

@@ -0,0 +1 @@
+"""Vendored protobuf message stubs for MCAP decoding."""

mcap2img/pb/proto/CameraCalibration.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+package foxglove;
+
+message CameraCalibration {
+  fixed32 width = 2;
+  fixed32 height = 3;
+  string distortion_model = 4;
+  repeated double D = 5;
+  repeated double K = 6;
+  repeated double P = 8;
+  repeated double T_b_c = 10;
+}

mcap2img/pb/proto/CompressedImage.proto

@@ -0,0 +1,7 @@
+syntax = "proto3";
+package foxglove;
+
+message CompressedImage {
+  bytes data = 2;
+  string format = 3;
+}

mcap2img/pb/proto/Pose.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+package foxglove;
+
+import "Quaternion.proto";
+import "Vector3.proto";
+
+message Pose {
+  Vector3 position = 1;
+  Quaternion orientation = 2;
+}

mcap2img/pb/proto/Quaternion.proto

@@ -0,0 +1,9 @@
+syntax = "proto3";
+package foxglove;
+
+message Quaternion {
+  double x = 1;
+  double y = 2;
+  double z = 3;
+  double w = 4;
+}

mcap2img/pb/proto/RobotInfo.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+package foxglove;
+
+import "Pose.proto";
+
+message RobotLinkInfo {
+  string name = 1;
+  Pose transform = 2;
+}
+
+enum BaselinkType {
+  BASELINK_TYPE_UNSPECIFIED = 0;
+  USE_BASELINK_AS_POSE = 1;
+  IGNORE_BASELINK = 2;
+}
+
+message RobotInfo {
+  RobotLinkInfo base_link = 8;
+  BaselinkType baselink_type = 9;
+}

mcap2img/pb/proto/Vector3.proto

@@ -0,0 +1,8 @@
+syntax = "proto3";
+package foxglove;
+
+message Vector3 {
+  double x = 1;
+  double y = 2;
+  double z = 3;
+}

mcap2img/progress.py

@@ -0,0 +1,41 @@
+"""Throttled progress logging for long-running batch jobs."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ProgressReporter:
+    """Log progress at most once per integer percent (or on completion)."""
+
+    def __init__(self, label: str, total: int | None = None) -> None:
+        self.label = label
+        self.total = int(total) if total is not None else None
+        self.done = 0
+        self._last_pct = -1
+
+    def advance(self, step: int = 1, *, force: bool = False) -> None:
+        self.done += step
+        if self.total and self.total > 0:
+            pct = min(100, int(self.done * 100 / self.total))
+            if force or pct != self._last_pct or self.done >= self.total:
+                self._last_pct = pct
+                logger.info(
+                    "%s: %d/%d (%d%%)",
+                    self.label,
+                    self.done,
+                    self.total,
+                    pct,
+                )
+            return
+
+        if force or self.done == 1 or self.done % 500 == 0:
+            logger.info("%s: %d ...", self.label, self.done)
+
+    def finish(self) -> None:
+        if self.total and self.total > 0:
+            self.advance(max(0, self.total - self.done), force=True)
+        else:
+            self.advance(0, force=True)