Release 1.0.1

Release Note

We noticed that some functions weren’t exposed at the top level.

In this release, we’re fixing that.

What's Changed

• fix: refactor imports and update all in utils module by @zephyr-sh in #34

Full Changelog: 1.0.0...1.0.1

Release 1.0.0

Quality Gates & Modular Runtimes

Capybara v1.0.0 marks the first “production-ready” baseline for the project: packaging is refactored to be lightweight by default, inference backends are moved to opt-in extras, and CI now enforces a strict quality gate (ruff + pyright + pytest + coverage gate). This release also reshapes the public API surface (capybara.__init__) to be explicit and stable.

---

Highlights

1) Lightweight default install + opt-in inference backends

Capybara now installs core-only dependencies by default (vision / structures / utils). Heavy inference stacks are explicitly opt-in via extras.

Core install

pip install capybara-docsaid

Inference backends (optional)

# ONNX Runtime (CPU)
pip install "capybara-docsaid[onnxruntime]"

# ONNX Runtime (GPU)
pip install "capybara-docsaid[onnxruntime-gpu]"

# OpenVINO runtime
pip install "capybara-docsaid[openvino]"

# TorchScript runtime
pip install "capybara-docsaid[torchscript]"

# Install all runtimes
pip install "capybara-docsaid[all]"

Feature extras (optional)

pip install "capybara-docsaid[visualization]"  # matplotlib/pillow
pip install "capybara-docsaid[ipcam]"          # flask
pip install "capybara-docsaid[system]"         # psutil

---

2) New runtime registry for backend selection (capybara.runtime)

A new Runtime / Backend registry unifies backend naming and adds auto backend selection utilities.

from capybara.runtime import Runtime

print(Runtime.onnx.auto_backend_name())      # Priority: cuda -> tensorrt_rtx -> tensorrt -> cpu
print(Runtime.openvino.auto_backend_name())  # Priority: gpu -> npu -> cpu
print(Runtime.pt.auto_backend_name())        # Priority: cuda -> cpu

This removes duplicated, backend-specific heuristics and provides a single place to reason about execution targets.

---

3) ONNXEngine rewritten: ergonomic config, IO binding, benchmark, and better metadata

capybara.onnxengine is refactored into a clearer surface:

• EngineConfig defines high-level session/provider/run options.
• Optional IO binding (enable_io_binding=True) for performance.
• benchmark(...) returns throughput + latency stats.
• Metadata parsing now attempts JSON decoding for custom metadata values.
• Provider chains follow capybara.runtime.Backend provider specs.

Example

import numpy as np
from capybara.onnxengine import EngineConfig, ONNXEngine

engine = ONNXEngine(
    "model.onnx",
    backend="cpu",
    config=EngineConfig(enable_io_binding=False),
)

outputs = engine.run({"input": np.ones((1, 3, 224, 224), dtype=np.float32)})
print(outputs.keys())
print(engine.summary())
print(engine.benchmark({"input": np.ones((1, 3, 224, 224), dtype=np.float32)}, repeat=50, warmup=5))

Note: onnxruntime is now an optional dependency. Importing capybara.onnxengine without installing the corresponding extra will raise a clear ImportError.

---

4) New OpenVINOEngine + async queue abstraction

A brand-new capybara.openvinoengine module is introduced, with a stable synchronous API and an async queue wrapper that returns Futures.

Synchronous

import numpy as np
from capybara.openvinoengine import OpenVINOConfig, OpenVINODevice, OpenVINOEngine

engine = OpenVINOEngine(
    "model.xml",
    device=OpenVINODevice.cpu,
    config=OpenVINOConfig(num_requests=2),
)

outputs = engine.run({"input": np.ones((1, 3), dtype=np.float32)})
print(outputs.keys())
print(engine.summary())
print(engine.benchmark({"input": np.ones((1, 3), dtype=np.float32)}, repeat=50, warmup=5))

Async (queue + Future)

import numpy as np
from capybara.openvinoengine import OpenVINOEngine

engine = OpenVINOEngine("model.xml", device="CPU")

with engine.create_async_queue(num_requests=2) as q:
    fut = q.submit({"input": np.ones((1, 3), dtype=np.float32)}, request_id="req-1")
    raw_outputs = fut.result()
    print(fut.request_id, raw_outputs.keys())

---

5) New TorchEngine for TorchScript runtime

capybara.torchengine provides a small, consistent wrapper around TorchScript:

• Handles dtype inference (fp16 naming + CUDA) and dtype normalization.
• benchmark(...) includes optional CUDA synchronization to avoid misleading timings.
• Outputs are normalized into dict[str, np.ndarray].

import numpy as np
from capybara.torchengine import TorchEngine

engine = TorchEngine("model.pt", device="cpu")
outputs = engine.run({"image": np.zeros((1, 3, 224, 224), dtype=np.float32)})
print(outputs.keys())
print(engine.summary())

---

Public API changes

1) capybara.__init__ is now explicit and curated

Instead of wildcard exports (from .xxx import *), v1.0.0 exports a curated stable API set and defines __all__. This improves:

• import speed,
• static analysis quality (pyright),
• backwards predictability.

import capybara as cb

print(cb.__version__)  # 1.0.0
from capybara import Box, Boxes, Polygon, Polygons, imread, imwrite

2) Backend moved to capybara.runtime

The old capybara.onnxengine.enum.Backend is removed; use:

from capybara.runtime import Backend

---

Quality Gates: CI is now enforced

What CI runs

A new GitHub Actions workflow Capybara CI is introduced:

• ruff check capybara tests
• ruff format --check capybara tests
• pyright
• pytest --cov=capybara ...
• coverage gate enforced

Coverage gate thresholds in CI:

• Line coverage: 0.99 (99%)
• Branch coverage: 0.00
• Enforced: 1 (hard fail)

Coverage config

.coveragerc is added to omit unstable / vendored / environment-dependent files from the gate, keeping CI reproducible.

CI reporting

CI generates and uploads an artifact containing:

• pytest.xml, pytest.html, coverage.xml, htmlcov/
• summary markdown + top slow tests
• coverage missing report
• logs for ruff/pyright/pytest

---

Packaging & tooling modernization

1) pyproject.toml becomes the single source of truth

• Removed legacy setup.py.
• Raised build requirements: setuptools>=68.
• Declared Python classifiers up to 3.14.
• Added optional dependencies groups (onnxruntime, onnxruntime-gpu, openvino, torchscript, system, ipcam, visualization, all).

2) pyrightconfig.json added

Basic type checking is enabled for capybara and tests, with pragmatic stub handling:

{
  "include": ["capybara", "tests"],
  "exclude": ["tmp", "capybara/cpuinfo.py"],
  "pythonVersion": "3.10",
  "typeCheckingMode": "basic",
  "reportMissingTypeStubs": false
}

3) Ruff config added and standardized formatting

ruff and ruff format are now first-class. The repo enforces:

• py310 target
• line-length=80
• lint selections (E/F/W/B/UP/N/I/C4/SIM/RUF)
• formatting normalization (double quotes, docstring code format, etc.)

---

Notable implementation hardening (bug fixes / behavioral improvements)

This release includes a large set of defensive fixes and API correctness improvements. A non-exhaustive set of high-impact ones:

• imwrite() no longer pollutes cwd with tmp.jpg; uses a safe temp file when path is omitted.
• pad() and imrotate() correctly handle RGBA channel counts and validate pad_value/bordervalue.
• Visualization no longer auto-downloads fonts; it falls back gracefully when font files are missing.
• Keypoints no longer hard-depends on matplotlib; it falls back to a pure-python colormap.
• PowerDict semantics tightened: proper AttributeError, safer update/pop, clear freeze/melt errors.
• get_files() no longer returns directories when suffix=None.
• video2frames / video2frames_v2 now validate edge cases (fps=0, n_threads, empty segments) and behave deterministically.

---

Upgrade notes

Install name change in README badges/links

PyPI package naming is standardized to capybara-docsaid in documentation.

If you previously relied on implicit heavy deps

v1.0.0 will require you to install extras explicitly. For example, ONNX users must install:

pip install "capybara-docsaid[onnxruntime]"        # or [onnxruntime-gpu]

---

New Contributors

• @Copilot made their first contribution in #30

Full Changelog: 0.12.0...1.0.0

Release 0.12.0

Release Note

What's Changed

• Enhance Keypoints Serialization and Refactor Codebase for Consistency and Readability by @kunkunlin1221 in #28

Full Changelog: 0.11.0...0.12.0

Release 0.11.0

Release Note

What's Changed

• [C] Replace onnxsim to onnxslim and rm setup.cfg by @kunkunlin1221 in #27

Full Changelog: 0.10.0...0.11.0

Release 0.10.0

Release Note

Updated

We updated opencv-python to support numpy > 2.0.

New inference backend

We include CoreML as onnxruntime backend for Mac user.

import capybara as cb
engine = cb.ONNXEngine(model_path, backend="coreml")

What's Changed

• [C] Update opencv for numpy>2.0 by @kunkunlin1221 in #26

Full Changelog: 0.9.0...0.10.0

Release 0.9.0

Release Note

✨ New Features

Area

Description

Detection Visualization

Added draw_detection() and draw_detections() for one‑line rendering of bounding boxes with class labels and optional confidence scores. • Auto‑generated, visually distinct box colours using golden‑ratio hue hashing. • Dynamic line thickness proportional to image size. • Optional box opacity (box_alpha) and translucent text‑background (text_bg_alpha). • Automatic font sizing (~10 % of box height) with sensible minimum.

🛠 Improvements

• Font handling

  • Introduced DEFAULT_FONT_PATH constant; all drawing utilities now fall back to this path consistently.
  • Existing Google‑Drive download logic reused if the font is missing.

🐞 Fixes

• draw_text() now respects the unified font path (DEFAULT_FONT_PATH), preventing “file not found” errors when custom fonts are omitted.

---

Upgrade Notes

This is a minor release (semver 0.x), fully backward‑compatible with v0.8.x.
Simply update and enjoy richer visualisation utilities:

pip install --upgrade capybara-docsaid==0.9.0

Happy coding!

Full Changelog: 0.8.3...0.9.0

Release 0.8.3

Release Note

Enhanced Google Drive Download Handling

• Improved authentication flow for large file downloads:
  • First, attempt to retrieve the download_warning parameter from cookies.
  • If no cookies are available, parse the HTML response to extract the confirm token or download link.
  • If the HTML contains form#download-form, extract the action URL and hidden fields for a new request.
• Ensured progress bar correctly reflects download progress and prevents empty chunks from being written.

Dependency Update

• Added beautifulsoup4 to the dependencies (setup.cfg) to support HTML parsing.

This release optimizes the Google Drive download process, improving reliability and stability for large file downloads.

What's Changed

• [F] Fixed download_from_google error by @zephyr-sh in #24

Full Changelog: 0.8.2...0.8.3

Release 0.8.2

Release Note

This release introduces multiple improvements, including enhanced ONNX metadata handling, support for dynamic axes in ONNX models, better formatting consistency, and test suite enhancements.

ONNX Metadata Improvements

• Replaced get_onnx_metadata with parse_metadata_from_onnx, ensuring consistent metadata parsing.
• Updated write_metadata_into_onnx to always serialize metadata as JSON.
• Refactored metadata formatting in ONNXEngine and ONNXEngineIOBinding.

Support for Dynamic Axes in ONNX Models

• Introduced make_onnx_dynamic_axes, which enables dynamic axes in ONNX models while ensuring compatibility with onnxsim.
• Added corresponding test cases to validate the functionality.

Code Cleanup and Formatting Standardization

• Switched all string literals to double quotes for consistency.
• Removed redundant blank lines and reformatted multi-line function calls for better readability.
• Improved dictionary formatting and standardized function parameter naming conventions.

Download Function Enhancement

• Integrated tqdm into download_from_google, providing a progress bar for file downloads.

Testing and Resource Updates

• Added new test cases for ONNX tools, including test_make_onnx_dynamic_axes.
• Replaced the outdated model.onnx test model with model_dynamic-axes.onnx and model_shape=224x224.onnx.
• Introduced make_onnx.py to generate ONNX models for testing, supporting both fixed and dynamic axes.

This release enhances ONNX model flexibility, improves metadata handling, and streamlines testing and formatting. If you encounter any issues or have suggestions, feel free to report them. Thanks for your support!

What's Changed

• [C] update metadata functions by @kunkunlin1221 in #23

Full Changelog: 0.8.1...0.8.2

Release 0.7.0

Release Note

1. Key Changes in Configuration Files

Pylint Configuration (.pylintrc)

• Updated overgeneral-exceptions setting:
  • Before: BaseException, Exception
  • After: builtins.BaseException, builtins.Exception

GitHub Workflow (pull_request.yml)

• Added paths-ignore directive to exclude specific paths and files from triggering workflow runs:
  • Ignored files: **/version.h, doc/**, **.md.
• Introduced environment variables:
  • DOCKERFILE: docker/pr.dockerfile
• Separated workflows into multiple jobs:
  1. Get Runner and UID: Fetches the runner and user/group IDs.
  2. Build Docker Image: Builds and pushes the Docker image for CI.
  3. CI Job: Executes tests using the newly built Docker image.
• Updated testing steps:
  • Reorganized installation commands for Python dependencies.
  • Enhanced error handling during wheel package installation.
  • Added GPU options for container execution.
• Improved test coverage reporting using pytest-cov.

---

2. Dockerfile Additions

docker/pr.dockerfile

• New Dockerfile for building CI environments.
• Key features:
  • Based on nvcr.io/nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04.
  • Installs essential tools and libraries, including:
    • ffmpeg, libturbojpeg, exiftool, python3-pip, and more.

---

3. Updates in ONNXEngine Module

capybara/onnxengine/__init__.py

• Added a new import: ONNXEngineIOBinding from engine_io_binding.

capybara/onnxengine/engine.py

• Enhanced __repr__ method:
  • Added utility to remove ANSI escape codes for cleaner output.
  • Improved formatting of nested dictionaries and centered title text.
• Refactored format_nested_dict to handle more complex data structures.

New Module: capybara/onnxengine/engine_io_binding.py

• Introduced a new class ONNXEngineIOBinding:
  • Implements advanced input-output binding for ONNXRuntime.
  • Supports GPU execution with enhanced session configuration options.
  • Handles nested input-output information for models dynamically.

---

4. Test Suite Enhancements

New Tests

• tests/onnxruntime/test_engine.py:
  • Validates ONNXEngine functionality with randomized inputs.
  • Ensures model outputs differ across runs.
• tests/onnxruntime/test_engine_io_binding.py:
  • Tests ONNXEngineIOBinding with dynamic input initializations.
  • Verifies output correctness and variance across executions.

New Resource

• ONNX Model (tests/resources/model.onnx):
  • Added a sample ONNX model for testing purposes.

Full Changelog: 0.6.0...0.7.0

Release 0.6.0

Release Note

1. Fixing a bug in the prepare_box function. The argument named src_mode should be based on input when input is a cb.Box.
2. Add get_onnx_input_infos and get_onnx_output_infos.

What's Changed

• [F] Fix prepare_box of src_mode by @kunkunlin1221 in #17
• [A] add tools for onnxengine by @kunkunlin1221 in #16

Full Changelog: 0.5.2...0.6.0