Running inference with a trained (single) detector

docs/source/_templates/autosummary/class.rst

@@ -3,9 +3,8 @@
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
-   {% if objname != 'ValidDataset' %}:members:{% endif %}
-   {% if objname != 'ValidDataset' %}:inherited-members:{% endif %}
-   {% if objname == 'ValidBboxAnnotationsDataFrame' %}:exclude-members: Config{% endif %}
+   :members:
+   :show-inheritance:
 
    {% block methods %}
    {% set ns = namespace(has_public_methods=false) %}
@@ -24,11 +23,13 @@
    .. autosummary::
    {% for item in methods %}
    {% if not item.startswith('_') %}
-      ~{{ name }}.{{ item }}
+      {{ item|is_own_method(name, module) }}
    {% endif %}
    {%- endfor %}
    {% endif %}
    {% endblock %}
 
+   .. rubric:: {{ _('Details') }}
+
 .. minigallery:: {{ module }}.{{ objname }}
    :add-heading: Examples using ``{{ objname }}``

docs/source/conf.py

@@ -1,9 +1,12 @@
 """Sphinx configuration for ethology documentation."""
 
+import inspect
 import os
 import sys
+from importlib import import_module
 from importlib.metadata import version as get_version
 
+from jinja2.filters import FILTERS
 from sphinx_gallery import sorting
 
 # Used when building API docs, put the dependencies
@@ -68,6 +71,7 @@
 # Automatically add anchors to markdown headings
 myst_heading_anchors = 4
 
+# -------- Autosummary
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -76,6 +80,47 @@
 autosummary_generate_overwrite = False
 autodoc_default_options = {"show-inheritance": True}  # applies to all classes
 
+
+def is_own_method(method_name, obj, module_name):
+    """Check if a method is defined in the class itself (not inherited).
+
+    Returns the method reference string if it's defined in the class,
+    empty string otherwise.
+    """
+    module = import_module(module_name)
+    if hasattr(module, "__all__") and obj not in module.__all__:
+        return ""
+
+    cls = getattr(module, obj)
+    if not inspect.isclass(cls):
+        return ""
+
+    # Check if method is defined in this class (not inherited)
+    if hasattr(cls, method_name):
+        # Check if it's in the class's __dict__ (defined in this class)
+        if method_name in cls.__dict__:
+            return f"~{obj}.{method_name}"
+        # Or check using inspect to see if it's defined in this class
+        try:
+            method = getattr(cls, method_name)
+            if inspect.ismethod(method) or inspect.isfunction(method):
+                # Check if the method's defining class is this class
+                if hasattr(method, "__qualname__"):
+                    qualname_parts = method.__qualname__.split(".")
+                    if len(qualname_parts) >= 2 and qualname_parts[-2] == obj:
+                        return f"~{obj}.{method_name}"
+                # Fallback: check if it's in __dict__
+                if method_name in cls.__dict__:
+                    return f"~{obj}.{method_name}"
+        except (AttributeError, TypeError):
+            pass
+
+    return ""
+
+
+FILTERS["is_own_method"] = is_own_method
+
+# -------------
 # Prefix section labels with the document name
 autosectionlabel_prefix_document = True
 
@@ -197,6 +242,9 @@
         "https://python-jsonschema.readthedocs.io/en/stable/",
         None,
     ),
+    "torch": ("https://pytorch.org/docs/stable/", None),
+    "torchvision": ("https://pytorch.org/vision/stable/", None),
+    "lightning": ("https://lightning.ai/docs/pytorch/stable/", None),
 }
 
 
@@ -221,7 +269,6 @@
 
 
 # sphinx-gallery configuration
-
 sphinx_gallery_conf = {
     "examples_dirs": ["../../examples"],
     "within_subsection_order": sorting.ExplicitOrder(

ethology/datasets/inference.py

@@ -0,0 +1,143 @@
+"""Datasets and related utilities for inference without ground-truth."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import torch
+import torchvision.transforms.v2 as transforms
+from PIL import Image
+from torch.utils.data import Dataset
+
+
+class InferenceImageDataset(Dataset):
+    """A simple dataset for images with no ground-truth annotations.
+
+    The image files are sorted alphabetically. The annotations dictionary
+    returned by ``__getitem__`` is always empty to maintain a consistent
+    interface with training datasets.
+
+    Parameters
+    ----------
+    images_dir
+        Path to the root directory containing the images.
+    file_pattern
+           Glob pattern to match image filenames (e.g., "*.png", "*.jpg").
+    transforms
+        Transforms to apply to the images. If `None` (default), the
+        transforms from :func:`get_default_inference_transforms` are used.
+
+    Attributes
+    ----------
+    images_dir : pathlib.Path
+        Path to the root directory containing the images.
+    transforms : torchvision.transforms.v2.Compose
+        Transforms to apply to the images.
+    image_files : list[pathlib.Path]
+        List of paths to each of the image files, sorted
+        alphabetically.
+
+    See Also
+    --------
+    get_default_inference_transforms : Returns default transforms for
+        inference.
+
+    Examples
+    --------
+    Create a dataset from 100 ``.png`` files in the ``/path/to/images``
+    directory:
+
+    >>> from ethology.datasets.inference import InferenceImageDataset
+    >>> dataset = InferenceImageDataset(
+    ...     images_dir="/path/to/images",
+    ...     file_pattern="*.png",
+    ... )
+    >>> len(dataset)
+    100
+
+    """
+
+    def __init__(
+        self,
+        images_dir: Path | str,
+        file_pattern: str,
+        transforms: transforms.Compose | None = None,
+    ):
+        """Initialise dataset."""
+        self.images_dir = Path(images_dir)
+        self.transforms = (
+            transforms
+            if transforms is not None
+            else get_default_inference_transforms()
+        )
+        self.image_files = sorted(self.images_dir.glob(file_pattern))
+
+    def __len__(self) -> int:
+        """Return the number of images in the dataset."""
+        return len(self.image_files)
+
+    def __getitem__(self, idx: int) -> tuple[torch.Tensor, dict]:
+        """Return the image and an empty annotations dictionary.
+
+        Parameters
+        ----------
+        idx : int
+            Index of the image to retrieve.
+
+        Returns
+        -------
+        tuple[torch.Tensor, dict]
+            A tuple containing the image as a tensor and an empty
+            annotations dictionary.
+
+        """
+        # Open requested image
+        img_path = Path(self.images_dir) / self.image_files[idx]
+        image = Image.open(img_path).convert("RGB")
+
+        # If transforms are specified, apply to the image
+        if self.transforms:
+            image = self.transforms(image)
+        return image, {}
+
+
+def get_default_inference_transforms() -> transforms.Compose:
+    """Return the default transforms for inference.
+
+    Transforms the input image to a tensor and scales the pixel
+    values from ``[0, 255]`` (uint8) to ``[0, 1]`` (float32).
+
+    Returns
+    -------
+    torchvision.transforms.v2.Compose
+        The default transforms for inference.
+
+    """
+    return transforms.Compose(
+        [
+            transforms.ToImage(),
+            transforms.ToDtype(torch.float32, scale=True),
+        ]
+    )
+
+
+def get_detector_collate_fn() -> Callable:
+    """Return collate function for a detector.
+
+    It supports images and annotations of different sizes.
+    A collate function takes a list of samples from a dataset
+    and batches them for the model to process it. Torch detectors
+    expect a list/tuple of images and annotations, since they can
+    be of different sizes across the dataset.
+
+    Returns
+    -------
+    Callable
+        A collate function for detector models.
+
+    """
+
+    def collate_fn(dataset_samples):
+        """Return a tuple of tuples: (images_tuple, annots_tuple)."""
+        return tuple(zip(*dataset_samples, strict=True))
+
+    return collate_fn