Metadata-Version: 2.4
Name: cv-frames
Version: 0.0.4
Summary: Read frames from OpenCV like humans
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
Requires-Dist: numpy
Requires-Dist: click
Provides-Extra: web
Requires-Dist: aiohttp; extra == "web"
Provides-Extra: opencv
Requires-Dist: opencv-python; extra == "opencv"
Provides-Extra: opencv-contrib
Requires-Dist: opencv-contrib-python; extra == "opencv-contrib"
Provides-Extra: opencv-headless
Requires-Dist: opencv-python-headless; extra == "opencv-headless"
Provides-Extra: opencv-contrib-headless
Requires-Dist: opencv-contrib-python-headless; extra == "opencv-contrib-headless"

cv-frames
=========

.. image:: https://github.com/kqf/cv-frames/actions/workflows/tests.yml/badge.svg
   :target: https://github.com/kqf/cv-frames/actions
   :alt: Tests

.. image:: https://img.shields.io/pypi/dm/cv-frames.svg
   :target: https://pypi.org/project/cv-frames/
   :alt: PyPI Downloads

``cv-frames`` is a lightweight utility that simplifies working with video files frame-by-frame using OpenCV.
It includes both a Python API and a command-line interface (CLI) for interacting with video frames in an intuitive way.

----

Installation
------------

Install via pip:

.. code-block:: bash

    pip install cv-frames

If you install ``cv-frames`` standalone, you need to specify an OpenCV backend:

.. code-block:: bash

    pip install cv-frames[opencv]

If ``cv-frames`` is part of a project that already depends on OpenCV
(e.g. ``opencv-python`` or ``opencv-contrib-python`` is listed in your
``requirements.txt``), no optional dependency is needed.

----

Command Line Usage
------------------

After installation, you can use the CLI:

.. code-block:: bash

    cv-frames show path/to/video.mp4

Navigate through frames with any key. Press **q** to quit.

----

Python Usage
------------

Example: Read and show frames programmatically

.. code-block:: python

    from pathlib import Path
    from cvframes import iterate

    for i, (_, frame) in enumerate(iterate(Path("video.mp4"))):
        print(f"Frame {i} shape:", frame.shape)

Example: Split side-by-side video into left/right frames

.. code-block:: python

    from cvframes import iterate_sbs

    # Write the processed frames to disc
    for capture, (left, right) in iterate_sbs("sbs_video.mp4", oname="processed.mp4"):
        processed = do_something(left)
        capture.write(processed)
