dataeval 0.69.3__py3-none-any.whl → 0.70.0__py3-none-any.whl

dataeval/_internal/metrics/stats/base.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import re
+import warnings
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, NamedTuple, Optional, Union
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from dataeval._internal.interop import to_numpy_iter
+from dataeval._internal.metrics.utils import normalize_box_shape, normalize_image_shape, rescale
+from dataeval._internal.output import OutputMetadata
+
+DTYPE_REGEX = re.compile(r"NDArray\[np\.(.*?)\]")
+SOURCE_INDEX = "source_index"
+BOX_COUNT = "box_count"
+
+OptionalRange = Optional[Union[int, Iterable[int]]]
+
+
+def matches(index: int | None, opt_range: OptionalRange) -> bool:
+    if index is None or opt_range is None:
+        return True
+    return index in opt_range if isinstance(opt_range, Iterable) else index == opt_range
+
+
+class SourceIndex(NamedTuple):
+    """
+    Attributes
+    ----------
+    image: int
+        Index of the source image
+    box : int | None
+        Index of the box of the source image
+    channel : int | None
+        Index of the channel of the source image
+    """
+
+    image: int
+    box: int | None
+    channel: int | None
+
+
+@dataclass(frozen=True)
+class BaseStatsOutput(OutputMetadata):
+    """
+    Attributes
+    ----------
+    source_index : List[SourceIndex]
+        Mapping from statistic to source image, box and channel index
+    box_count : NDArray[np.uint16]
+    """
+
+    source_index: list[SourceIndex]
+    box_count: NDArray[np.uint16]
+
+    def get_channel_mask(
+        self,
+        channel_index: OptionalRange,
+        channel_count: OptionalRange = None,
+    ) -> list[bool]:
+        """
+        Boolean mask for results filtered to specified channel index and optionally the count
+        of the channels per image.
+
+        Parameters
+        ----------
+        channel_index : int | Iterable[int] | None
+            Index or indices of channel(s) to filter for
+        channel_count : int | Iterable[int] | None
+            Optional count(s) of channels to filter for
+        """
+        mask: list[bool] = []
+        cur_mask: list[bool] = []
+        cur_image = 0
+        cur_max_channel = 0
+        for source_index in list(self.source_index) + [None]:
+            if source_index is None or source_index.image > cur_image:
+                mask.extend(cur_mask if matches(cur_max_channel + 1, channel_count) else [False for _ in cur_mask])
+                if source_index is None:
+                    break
+                cur_image = source_index.image
+                cur_max_channel = 0
+                cur_mask.clear()
+            cur_mask.append(matches(source_index.channel, channel_index))
+            cur_max_channel = max(cur_max_channel, source_index.channel or 0)
+        return mask
+
+    def __len__(self) -> int:
+        return len(self.source_index)
+
+
+class StatsProcessor:
+    cache_keys: list[str] = []
+    image_function_map: dict[str, Callable[[StatsProcessor], Any]] = {}
+    channel_function_map: dict[str, Callable[[StatsProcessor], Any]] = {}
+
+    def __init__(self, image: NDArray, box: NDArray | None, per_channel: bool):
+        self.raw = image
+        self.width = image.shape[-1]
+        self.height = image.shape[-2]
+        self.box = np.array([0, 0, self.width, self.height]) if box is None else box
+        self.per_channel = per_channel
+        self._image = None
+        self._shape = None
+        self._scaled = None
+        self.cache = {}
+        self.fn_map = self.channel_function_map if per_channel else self.image_function_map
+        self.is_valid_slice = box is None or bool(
+            box[0] >= 0 and box[1] >= 0 and box[2] <= image.shape[-1] and box[3] <= image.shape[-2]
+        )
+
+    def get(self, fn_key: str) -> NDArray:
+        if fn_key in self.cache_keys:
+            if fn_key not in self.cache:
+                self.cache[fn_key] = self.fn_map[fn_key](self)
+            return self.cache[fn_key]
+        else:
+            return self.fn_map[fn_key](self)
+
+    @property
+    def image(self) -> NDArray:
+        if self._image is None:
+            if self.is_valid_slice:
+                norm = normalize_image_shape(self.raw)
+                self._image = norm[:, self.box[1] : self.box[3], self.box[0] : self.box[2]]
+            else:
+                self._image = np.zeros((self.raw.shape[0], self.box[3] - self.box[1], self.box[2] - self.box[0]))
+        return self._image
+
+    @property
+    def shape(self) -> tuple:
+        if self._shape is None:
+            self._shape = self.image.shape
+        return self._shape
+
+    @property
+    def scaled(self) -> NDArray:
+        if self._scaled is None:
+            self._scaled = rescale(self.image)
+            if self.per_channel:
+                self._scaled = self._scaled.reshape(self.image.shape[0], -1)
+        return self._scaled
+
+
+def run_stats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None,
+    per_channel: bool,
+    stats_processor_cls: type,
+    output_cls: type,
+) -> dict:
+    """
+    Compute specified statistics on a set of images.
+
+    This function applies a set of statistical operations to each image in the input iterable,
+    based on the specified output class. The function determines which statistics to apply
+    using a function map. It also supports optional image flattening for pixel-wise calculations.
+
+    Parameters
+    ----------
+    images : Iterable[ArrayLike]
+        An iterable of images (e.g., list of arrays), where each image is represented as an
+        array-like structure (e.g., NumPy arrays).
+    bboxes : Iterable[ArrayLike]
+        An iterable of bounding boxes (e.g. list of arrays) where each bounding box is represented
+        as an array-like structure in the format of (X0, Y0, X1, Y1). The length of the bounding boxes
+        iterable should match the length of the input images.
+    per_channel : bool
+        A flag which determines if the states should be evaluated on a per-channel basis or not.
+    output_cls : type
+        The output class for which stats values will be calculated.
+
+    Returns
+    -------
+    dict[str, NDArray]]
+        A dictionary containing the computed statistics for each image.
+        The dictionary keys correspond to the names of the statistics, and the values are NumPy arrays
+        with the results of the computations.
+
+    Notes
+    -----
+    - The function performs image normalization (rescaling the image values)
+      before applying some of the statistics.
+    - Pixel-level statistics (e.g., brightness, entropy) are computed after
+      rescaling and, optionally, flattening the images.
+    - For statistics like histograms and entropy, intermediate results may
+      be reused to avoid redundant computation.
+    """
+    results_list: list[dict[str, NDArray]] = []
+    output_list = list(output_cls.__annotations__)
+    source_index = []
+    box_count = []
+    bbox_iter = (None for _ in images) if bboxes is None else to_numpy_iter(bboxes)
+
+    for i, (boxes, image) in enumerate(zip(bbox_iter, to_numpy_iter(images))):
+        nboxes = [None] if boxes is None else normalize_box_shape(boxes)
+        for i_b, box in enumerate(nboxes):
+            i_b = None if box is None else i_b
+            processor: StatsProcessor = stats_processor_cls(image, box, per_channel)
+            if not processor.is_valid_slice:
+                warnings.warn(f"Bounding box {i_b}: {box} is out of bounds of image {i}: {image.shape}.")
+            results_list.append({stat: processor.get(stat) for stat in output_list})
+            if per_channel:
+                source_index.extend([SourceIndex(i, i_b, c) for c in range(image.shape[-3])])
+            else:
+                source_index.append(SourceIndex(i, i_b, None))
+        box_count.append(0 if boxes is None else len(boxes))
+
+    output = {}
+    if per_channel:
+        for i, results in enumerate(results_list):
+            for stat, result in results.items():
+                output.setdefault(stat, []).extend(result.tolist())
+    else:
+        for results in results_list:
+            for stat, result in results.items():
+                output.setdefault(stat, []).append(result.tolist() if isinstance(result, np.ndarray) else result)
+
+    for stat in output:
+        stat_type: str = output_cls.__annotations__[stat]
+
+        dtype_match = re.match(DTYPE_REGEX, stat_type)
+        if dtype_match is not None:
+            output[stat] = np.asarray(output[stat], dtype=np.dtype(dtype_match.group(1)))
+
+    output[SOURCE_INDEX] = source_index
+    output[BOX_COUNT] = np.asarray(box_count, dtype=np.uint16)
+
+    return output

dataeval/_internal/metrics/stats/boxratiostats.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import copy
+from typing import Callable, Generic, TypeVar, cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+from dataeval._internal.metrics.stats.base import BOX_COUNT, SOURCE_INDEX, BaseStatsOutput
+from dataeval._internal.metrics.stats.dimensionstats import DimensionStatsOutput
+from dataeval._internal.output import set_metadata
+
+TStatOutput = TypeVar("TStatOutput", bound=BaseStatsOutput, contravariant=True)
+ArraySlice = tuple[int, int]
+
+
+class BoxImageStatsOutputSlice(Generic[TStatOutput]):
+    class StatSlicer:
+        def __init__(self, stats: TStatOutput, slice: ArraySlice, channels: int = 0) -> None:  # noqa: A002
+            self._stats = stats
+            self._slice = slice
+            self._channels = channels
+
+        def __getitem__(self, key: str) -> NDArray[np.float64]:
+            _stat = cast(np.ndarray, getattr(self._stats, key)).astype(np.float64)
+            _shape = _stat[0].shape
+            _slice = _stat[self._slice[0] : self._slice[1]]
+            return _slice.reshape(-1, self._channels, *_shape) if self._channels else _slice.reshape(-1, *_shape)
+
+    box: StatSlicer
+    img: StatSlicer
+    channels: int
+
+    def __init__(
+        self, box_stats: TStatOutput, box_slice: ArraySlice, img_stats: TStatOutput, img_slice: ArraySlice
+    ) -> None:
+        self.channels = img_slice[1] - img_slice[0]
+        self.box = self.StatSlicer(box_stats, box_slice, self.channels)
+        self.img = self.StatSlicer(img_stats, img_slice)
+
+
+RATIOSTATS_OVERRIDE_MAP: dict[type, dict[str, Callable[[BoxImageStatsOutputSlice], NDArray]]] = {
+    DimensionStatsOutput: {
+        "left": lambda x: x.box["left"] / x.img["width"],
+        "top": lambda x: x.box["top"] / x.img["height"],
+        "channels": lambda x: x.box["channels"],
+        "depth": lambda x: x.box["depth"],
+        "distance": lambda x: x.box["distance"],
+    }
+}
+
+
+def get_index_map(stats: BaseStatsOutput) -> list[int]:
+    index_map: list[int] = []
+    cur_index = -1
+    for i, s in enumerate(stats.source_index):
+        if s.image > cur_index:
+            index_map.append(i)
+            cur_index = s.image
+    return index_map
+
+
+def calculate_ratios(key: str, box_stats: BaseStatsOutput, img_stats: BaseStatsOutput) -> NDArray:
+    if not hasattr(box_stats, key) or not hasattr(img_stats, key):
+        raise KeyError("Invalid key for provided stats output object.")
+
+    stats = getattr(box_stats, key)
+
+    # Copy over stats index maps and box counts
+    if key in (SOURCE_INDEX):
+        return copy.deepcopy(stats)
+    elif key == BOX_COUNT:
+        return np.copy(stats)
+
+    # Calculate ratios for each stat
+    out_stats: np.ndarray = np.copy(stats).astype(np.float64)
+
+    box_map = get_index_map(box_stats)
+    img_map = get_index_map(img_stats)
+    for i, (box_i, img_i) in enumerate(zip(box_map, img_map)):
+        box_j = len(box_stats) if i == len(box_map) - 1 else box_map[i + 1]
+        img_j = len(img_stats) if i == len(img_map) - 1 else img_map[i + 1]
+        stats = BoxImageStatsOutputSlice(box_stats, (box_i, box_j), img_stats, (img_i, img_j))
+        out_type = type(box_stats)
+        use_override = out_type in RATIOSTATS_OVERRIDE_MAP and key in RATIOSTATS_OVERRIDE_MAP[out_type]
+        ratio = (
+            RATIOSTATS_OVERRIDE_MAP[out_type][key](stats)
+            if use_override
+            else np.nan_to_num(stats.box[key] / stats.img[key])
+        )
+        out_stats[box_i:box_j] = ratio.reshape(-1, *out_stats[box_i].shape)
+    return out_stats
+
+
+@set_metadata("dataeval.metrics")
+def boxratiostats(
+    boxstats: TStatOutput,
+    imgstats: TStatOutput,
+) -> TStatOutput:
+    """
+    Calculates ratio statistics of box outputs over image outputs
+
+    Parameters
+    ----------
+    boxstats : DimensionStatsOutput | PixelStatsOutput | VisualStatsOutput
+        Box statistics outputs to perform calculations on
+    imgstats : DimensionStatsOutput | PixelStatsOutput | VisualStatsOutput
+        Image statistics outputs to perform calculations on
+
+    Returns
+    -------
+    DimensionStatsOutput | PixelStatsOutput | VisualStatsOutput
+        A dictionary-like object containing the computed ratio of the box statistics divided by the
+        image statistics.
+
+    See Also
+    --------
+    dimensionstats, pixelstats, visualstats
+
+    Note
+    ----
+    DimensionStatsOutput values for channels, depth and distances are the original values
+    provided by the box outputs
+
+    Examples
+    --------
+    Calculating the box ratio statistics using the dimension stats of the boxes and images
+
+    >>> imagestats = dimensionstats(images)
+    >>> boxstats = dimensionstats(images, bboxes)
+    >>> ratiostats = boxratiostats(boxstats, imagestats)
+    >>> print(ratiostats.aspect_ratio)
+    [ 1.15169271  0.78450521 21.33333333  1.5234375   2.25651042  0.77799479
+      0.88867188  3.40625     1.73307292  1.11132812  0.75018315  0.45018315
+      0.69596354 20.          5.11197917  2.33333333  0.75        0.70019531]
+    >>> print(ratiostats.size)
+    [0.03401693 0.01383464 0.00130208 0.01822917 0.02327474 0.00683594
+     0.01220703 0.0168457  0.01057943 0.00976562 0.00130208 0.01098633
+     0.02246094 0.0012207  0.01123047 0.00911458 0.02636719 0.06835938]
+    """
+    output_cls = type(boxstats)
+    if type(boxstats) is not type(imgstats):
+        raise TypeError("Must provide stats outputs of the same type.")
+    if boxstats.source_index[-1].image != imgstats.source_index[-1].image:
+        raise ValueError("Stats index_map length mismatch. Check if the correct box and image stats were provided.")
+    if all(count == 0 for count in boxstats.box_count):
+        raise TypeError("Input for boxstats must contain box information.")
+    if any(count != 0 for count in imgstats.box_count):
+        raise TypeError("Input for imgstats must not contain box information.")
+    boxstats_has_channels = any(si.channel is None for si in boxstats.source_index)
+    imgstats_has_channels = any(si.channel is None for si in imgstats.source_index)
+    if boxstats_has_channels != imgstats_has_channels:
+        raise TypeError("Input for boxstats and imgstats must have matching channel information.")
+
+    output_dict = {}
+    for key in boxstats.dict():
+        output_dict[key] = calculate_ratios(key, boxstats, imgstats)
+
+    return output_cls(**output_dict)

dataeval/_internal/metrics/stats/datasetstats.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from numpy.typing import ArrayLike
+
+from dataeval._internal.metrics.stats.base import BaseStatsOutput
+from dataeval._internal.metrics.stats.dimensionstats import DimensionStatsOutput, dimensionstats
+from dataeval._internal.metrics.stats.labelstats import LabelStatsOutput, labelstats
+from dataeval._internal.metrics.stats.pixelstats import PixelStatsOutput, pixelstats
+from dataeval._internal.metrics.stats.visualstats import VisualStatsOutput, visualstats
+from dataeval._internal.output import OutputMetadata, set_metadata
+
+
+@dataclass(frozen=True)
+class DatasetStatsOutput(OutputMetadata):
+    """
+    This class represents the outputs of various stats functions against a single
+    dataset, such that each index across all stat outputs are representative of
+    the same source image.  Modifying or mixing outputs will result in inaccurate
+    outlier calculations if not created correctly.
+
+    Attributes
+    ----------
+    dimensionstats : DimensionStatsOutput or None
+    pixelstats: PixelStatsOutput or None
+    visualstats: VisualStatsOutput or None
+    labelstats: LabelStatsOutput or None, default None
+    """
+
+    dimensionstats: DimensionStatsOutput | None
+    pixelstats: PixelStatsOutput | None
+    visualstats: VisualStatsOutput | None
+    labelstats: LabelStatsOutput | None = None
+
+    def outputs(self) -> list[BaseStatsOutput]:
+        return [s for s in (self.dimensionstats, self.pixelstats, self.visualstats) if s is not None]
+
+    def __post_init__(self):
+        lengths = [len(s) for s in self.outputs()]
+        if not all(length == lengths[0] for length in lengths):
+            raise ValueError("All StatsOutput classes must contain the same number of image sources.")
+
+
+@set_metadata("dataeval.metrics")
+def datasetstats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None = None,
+    labels: Iterable[ArrayLike] | None = None,
+    use_dimension: bool = True,
+    use_pixel: bool = True,
+    use_visual: bool = True,
+) -> DatasetStatsOutput:
+    """
+    Calculates various statistics for each image
+
+    This function computes dimension, pixel and visual metrics
+    on the images or individual bounding boxes for each image as
+    well as label statistics if provided.
+
+    Parameters
+    ----------
+    images : Iterable[ArrayLike]
+        Images to perform calculations on
+    bboxes : Iterable[ArrayLike] or None
+        Bounding boxes in `xyxy` format for each image to perform calculations on
+    labels : Iterable[ArrayLike] or None
+        Labels of images or boxes to perform calculations on
+
+    Returns
+    -------
+    DatasetStatsOutput
+        Output class containing the outputs of various stats functions
+
+    See Also
+    --------
+    dimensionstats, labelstats, pixelstats, visualstats, Outliers
+
+    Examples
+    --------
+    Calculating the dimension, pixel and visual stats for a dataset with bounding boxes
+
+    >>> stats = datasetstats(images, bboxes)
+    >>> print(stats.dimensionstats.aspect_ratio)
+    [ 0.864   0.5884 16.      1.143   1.692   0.5835  0.6665  2.555   1.3
+      0.8335  1.      0.6     0.522  15.      3.834   1.75    0.75    0.7   ]
+    >>> print(stats.visualstats.contrast)
+    [1.744   1.946   0.1164  0.0635  0.0633  0.06274 0.0429  0.0317  0.0317
+     0.02576 0.02081 0.02171 0.01915 0.01767 0.01799 0.01595 0.01433 0.01478]
+    """
+    return DatasetStatsOutput(
+        dimensionstats(images, bboxes) if use_dimension else None,
+        pixelstats(images, bboxes) if use_pixel else None,
+        visualstats(images, bboxes) if use_visual else None,
+        labelstats(labels) if labels else None,
+    )

dataeval/_internal/metrics/stats/dimensionstats.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from dataeval._internal.metrics.stats.base import BaseStatsOutput, StatsProcessor, run_stats
+from dataeval._internal.metrics.utils import get_bitdepth
+from dataeval._internal.output import set_metadata
+
+
+class DimensionStatsProcessor(StatsProcessor):
+    image_function_map = {
+        "left": lambda x: x.box[0],
+        "top": lambda x: x.box[1],
+        "width": lambda x: x.shape[-1],
+        "height": lambda x: x.shape[-2],
+        "channels": lambda x: x.shape[-3],
+        "size": lambda x: np.prod(x.shape[-2:]),
+        "aspect_ratio": lambda x: x.shape[-1] / x.shape[-2],
+        "depth": lambda x: get_bitdepth(x.image).depth,
+        "center": lambda x: np.asarray([(x.box[0] + x.box[2]) / 2, (x.box[1] + x.box[3]) / 2]),
+        "distance": lambda x: np.sqrt(
+            np.square(((x.box[0] + x.box[2]) / 2) - (x.width / 2))
+            + np.square(((x.box[1] + x.box[3]) / 2) - (x.height / 2))
+        ),
+    }
+
+
+@dataclass(frozen=True)
+class DimensionStatsOutput(BaseStatsOutput):
+    """
+    Attributes
+    ----------
+    left : NDArray[np.int32]
+        Offsets from the left edge of images in pixels
+    top : NDArray[np.int32]
+        Offsets from the top edge of images in pixels
+    width : NDArray[np.uint32]
+        Width of the images in pixels
+    height : NDArray[np.uint32]
+        Height of the images in pixels
+    channels : NDArray[np.uint8]
+        Channel count of the images in pixels
+    size : NDArray[np.uint32]
+        Size of the images in pixels
+    aspect_ratio : NDArray[np.float16]
+        Aspect ratio of the images (width/height)
+    depth : NDArray[np.uint8]
+        Color depth of the images in bits
+    center : NDArray[np.uint16]
+        Offset from center in [x,y] coordinates of the images in pixels
+    distance : NDArray[np.float16]
+        Distance in pixels from center
+    """
+
+    left: NDArray[np.int32]
+    top: NDArray[np.int32]
+    width: NDArray[np.uint32]
+    height: NDArray[np.uint32]
+    channels: NDArray[np.uint8]
+    size: NDArray[np.uint32]
+    aspect_ratio: NDArray[np.float16]
+    depth: NDArray[np.uint8]
+    center: NDArray[np.int16]
+    distance: NDArray[np.float16]
+
+
+@set_metadata("dataeval.metrics")
+def dimensionstats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None = None,
+) -> DimensionStatsOutput:
+    """
+    Calculates dimension statistics for each image
+
+    This function computes various dimensional metrics (e.g., width, height, channels)
+    on the images or individual bounding boxes for each image.
+
+    Parameters
+    ----------
+    images : Iterable[ArrayLike]
+        Images to perform calculations on
+    bboxes : Iterable[ArrayLike] or None
+        Bounding boxes in `xyxy` format for each image to perform calculations on
+
+    Returns
+    -------
+    DimensionStatsOutput
+        A dictionary-like object containing the computed dimension statistics for each image or bounding
+        box. The keys correspond to the names of the statistics (e.g., 'width', 'height'), and the values
+        are lists of results for each image or numpy arrays when the results are multi-dimensional.
+
+    See Also
+    --------
+    pixelstats, visualstats, Outliers
+
+    Examples
+    --------
+    Calculating the dimension statistics on the images, whose shape is (C, H, W)
+
+    >>> results = dimensionstats(images)
+    >>> print(results.aspect_ratio)
+    [0.75  0.75  0.75  0.75  0.75  0.75  1.333 0.75  0.75  1.   ]
+    >>> print(results.channels)
+    [1 1 1 1 1 1 3 1 1 3]
+    """
+    output = run_stats(images, bboxes, False, DimensionStatsProcessor, DimensionStatsOutput)
+    return DimensionStatsOutput(**output)

dataeval/_internal/metrics/stats/hashstats.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from numpy.typing import ArrayLike
+
+from dataeval._internal.metrics.stats.base import BaseStatsOutput, StatsProcessor, run_stats
+from dataeval._internal.metrics.utils import pchash, xxhash
+from dataeval._internal.output import set_metadata
+
+
+class HashStatsProcessor(StatsProcessor):
+    image_function_map = {
+        "xxhash": lambda x: xxhash(x.image),
+        "pchash": lambda x: pchash(x.image),
+    }
+
+
+@dataclass(frozen=True)
+class HashStatsOutput(BaseStatsOutput):
+    """
+    Attributes
+    ----------
+    xxhash : List[str]
+        xxHash hash of the images as a hex string
+    pchash : List[str]
+        Perception hash of the images as a hex string
+    """
+
+    xxhash: list[str]
+    pchash: list[str]
+
+
+@set_metadata("dataeval.metrics")
+def hashstats(
+    images: Iterable[ArrayLike],
+    bboxes: Iterable[ArrayLike] | None = None,
+) -> HashStatsOutput:
+    """
+    Calculates hashes for each image
+
+    This function computes hashes from the images including exact hashes and perception-based
+    hashes. These hash values can be used to determine if images are exact or near matches.
+
+    Parameters
+    ----------
+    images : ArrayLike
+        Images to hashing
+    bboxes : Iterable[ArrayLike] or None
+        Bounding boxes in `xyxy` format for each image
+
+    Returns
+    -------
+    HashStatsOutput
+        A dictionary-like object containing the computed hashes for each image.
+
+    See Also
+    --------
+    Duplicates
+
+    Examples
+    --------
+    Calculating the statistics on the images, whose shape is (C, H, W)
+
+    >>> results = hashstats(images)
+    >>> print(results.xxhash)
+    ['a72434443d6e7336', 'efc12c2f14581d79', '4a1e03483a27d674', '3a3ecedbcf814226']
+    >>> print(results.pchash)
+    ['8f25506af46a7c6a', '8000808000008080', '8e71f18e0ef18e0e', 'a956d6a956d6a928']
+    """
+    output = run_stats(images, bboxes, False, HashStatsProcessor, HashStatsOutput)
+    return HashStatsOutput(**output)