Core library
============

QCamera
-------

.. automodule:: QVideo.lib.QCamera
   :members:

QVideoSource
------------

.. automodule:: QVideo.lib.QVideoSource
   :members:

QCameraTree
-----------

.. automodule:: QVideo.lib.QCameraTree
   :members:

QVideoScreen
------------

.. automodule:: QVideo.lib.QVideoScreen
   :members:

QFilterBank and VideoFilter
---------------------------

:class:`~QVideo.lib.QVideoFilter.VideoFilter` is the base class for all
image-processing filters.  Its ``add`` / ``get`` interface separates frame
ingestion from result production, supporting both stateless transforms
(override ``get`` only) and stateful accumulators (override both ``add`` and
``get``).

Stateless filters can also implement
:meth:`~QVideo.lib.QVideoFilter.VideoFilter.to_code`, which returns a
:class:`~QVideo.lib.QVideoFilter.FilterCode` fragment describing the OpenCV
and NumPy calls the filter makes.
:meth:`~QVideo.lib.QFilterRack.QFilterRack.exportPipeline` collects these
fragments to produce a standalone ``filter.py`` file.  See
:ref:`extending-export` for how to add export support to a custom filter.

.. automodule:: QVideo.lib.QFilterBank
   :members:

.. automodule:: QVideo.lib.QVideoFilter
   :members:

AsyncVideoFilter
----------------

:class:`~QVideo.lib.AsyncVideoFilter.AsyncVideoFilter` is a base class for
filters that run heavy computation in a background :class:`~qtpy.QtCore.QThread`
so the GUI remains responsive even when inference is slower than the camera
frame rate.  Frames are dropped rather than queued when the worker is busy,
preventing latency build-up.

Subclasses override :meth:`~QVideo.lib.AsyncVideoFilter.AsyncVideoFilter.process`
(called in the background thread) and inherit :meth:`add` / :meth:`get` /
:meth:`__call__` from the base.

.. automodule:: QVideo.lib.AsyncVideoFilter
   :members:

QFilterRack
-----------

:class:`~QVideo.lib.QFilterRack.QFilterRack` is a dynamic, user-editable
alternative to :class:`~QVideo.lib.QFilterBank.QFilterBank`.  It wraps each
filter in a slot that carries a ⋮ drag handle for reordering and a × button
for removal.  Set :attr:`~QVideo.lib.QFilterRack.QFilterRack.editable` to
``False`` to hide all editing controls while keeping the pipeline callable.

The toolbar provides two buttons:

**Add filter…**
  Opens a tree dialog listing all
  :class:`~QVideo.lib.QVideoFilter.QVideoFilter` subclasses exported by
  :mod:`QVideo.filters`, grouped by their
  :attr:`~QVideo.lib.QVideoFilter.QVideoFilter.display_category` class
  attribute.  Category headers are not selectable; clicking a leaf item and
  pressing **OK** (or double-clicking it) adds the filter to the rack.
  Filters without a ``display_category`` appear under *Other*.

**Export…**
  Saves the current pipeline as a standalone Python source file.  Only
  *enabled* (checked) filters are included.  Each filter's
  :meth:`~QVideo.lib.QVideoFilter.VideoFilter.to_code` method provides the
  code fragment and import set; the rack assembles them into a module with a
  ``filter(image: np.ndarray) -> np.ndarray`` function.  Filters that return
  ``None`` from ``to_code`` — typically stateful accumulators such as
  :class:`~QVideo.filters.foreground.ForegroundEstimator` — are skipped and
  noted in a comment.  The generated file is valid, immediately importable
  Python.

A typical exported file looks like this:

.. code-block:: python

   '''Image-processing pipeline generated by QVideo.'''

   import cv2
   import numpy as np


   def filter(image: np.ndarray) -> np.ndarray:
       # Gaussian smoothing, k=5
       image = cv2.GaussianBlur(image, (5, 5), 0)

       # Otsu threshold
       if image.ndim == 3:
           image = image.mean(axis=2).astype(np.uint8)
       image = cv2.threshold(image, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)[1]

       return image

.. automodule:: QVideo.lib.QFilterRack
   :members:

Camera chooser
--------------

.. automodule:: QVideo.lib.chooser
   :members:

QVideoReader
------------

.. automodule:: QVideo.lib.QVideoReader
   :members:

QVideoWriter
------------

.. automodule:: QVideo.lib.QVideoWriter
   :members:

QFPSMeter
---------

.. automodule:: QVideo.lib.QFPSMeter
   :members:

QSnapshot
---------

:class:`~QVideo.lib.QSnapshot.QSnapshot` captures the most recent frame
from any ``newFrame`` signal and saves it to disk on demand.  It has no
visual presence — drop it into any application as a :class:`~qtpy.QtCore.QObject`
and two keyboard shortcuts become available:

- ``Ctrl+Shift+S`` — save a timestamped PNG to the user's home directory
- ``Ctrl+Shift+Alt+S`` — open a file dialog pre-filled with the same name

The source connected to :meth:`~QVideo.lib.QSnapshot.QSnapshot.newFrame`
determines what is captured: raw frames (``QVideoSource.newFrame``),
filtered frames (``QVideoScreen.newFrame``), or the fully rendered scene
with overlays (``QVideoScreen.newFrame`` with ``composite=True``).

.. automodule:: QVideo.lib.QSnapshot
   :members:

QListCameras
------------

.. automodule:: QVideo.lib.QListCameras
   :members:

QCamcorder
----------

.. automodule:: QVideo.QCamcorder
   :members: