vws-python-mock 2026.8.4__py3-none-any.whl

mock_vws/database.py

@@ -0,0 +1,257 @@
+"""Utilities for managing mock Vuforia databases."""
+
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import NotRequired, Self, TypedDict
+
+from beartype import beartype
+
+from mock_vws._constants import TargetStatuses
+from mock_vws.database_type import DatabaseType
+from mock_vws.states import States
+from mock_vws.target import (
+    ImageTarget,
+    ImageTargetDict,
+    VuMarkTarget,
+    VuMarkTargetDict,
+)
+
+
+@beartype
+class CloudDatabaseDict(TypedDict):
+    """A dictionary type which represents a cloud database."""
+
+    database_name: str
+    server_access_key: str
+    server_secret_key: str
+    client_access_key: str
+    client_secret_key: str
+    state_name: str
+    database_type_name: str
+    targets: Iterable[ImageTargetDict]
+    request_quota: NotRequired[int]
+    target_quota: NotRequired[int]
+
+
+@beartype
+class VuMarkDatabaseDict(TypedDict):
+    """A dictionary type which represents a VuMark database."""
+
+    database_name: str
+    server_access_key: str
+    server_secret_key: str
+    vumark_targets: Iterable[VuMarkTargetDict]
+    state_name: str
+
+
+@beartype
+def _random_hex() -> str:
+    """Return a random hex value."""
+    return uuid.uuid4().hex
+
+
+@beartype
+@dataclass(eq=True, frozen=True, kw_only=True)
+class CloudDatabase:
+    """Credentials for VWS APIs.
+
+    Args:
+        database_name: The name of a VWS target manager database name. Defaults
+            to a random string.
+        server_access_key: A VWS server access key. Defaults to a random
+            string.
+        server_secret_key: A VWS server secret key. Defaults to a random
+            string.
+        client_access_key: A VWS client access key. Defaults to a random
+            string.
+        client_secret_key: A VWS client secret key. Defaults to a random
+            string.
+        state: The state of the database.
+        request_quota: The request quota. Set this to ``0`` to make VWS
+            endpoints return ``RequestQuotaReached``.
+        target_quota: The target quota. When the database contains this many
+            targets, adding another returns ``TargetQuotaReached``.
+    """
+
+    # We hide a few things in the ``repr`` with ``repr=False`` so that they do
+    # not show up in CI logs.
+    database_name: str = field(default_factory=_random_hex, repr=False)
+    server_access_key: str = field(default_factory=_random_hex, repr=False)
+    server_secret_key: str = field(default_factory=_random_hex, repr=False)
+    client_access_key: str = field(default_factory=_random_hex, repr=False)
+    client_secret_key: str = field(default_factory=_random_hex, repr=False)
+    # We have ``targets`` as ``hash=False`` so that we can have the class as
+    # ``frozen=True`` while still being able to keep the interface we want.
+    # In particular, we might want to inspect the ``database`` object's targets
+    # as they change via API requests.
+    targets: set[ImageTarget] = field(
+        default_factory=set[ImageTarget],
+        hash=False,
+    )
+    state: States = States.WORKING
+    database_type: DatabaseType = DatabaseType.CLOUD_RECO
+
+    request_quota: int = 100000
+    reco_threshold: int = 1000
+    current_month_recos: int = 0
+    previous_month_recos: int = 0
+    total_recos: int = 0
+    target_quota: int = 1000
+
+    def to_dict(self) -> CloudDatabaseDict:
+        """Dump a target to a dictionary which can be loaded as JSON."""
+        targets: list[ImageTargetDict] = [
+            target.to_dict() for target in self.targets
+        ]
+        return {
+            "database_name": self.database_name,
+            "server_access_key": self.server_access_key,
+            "server_secret_key": self.server_secret_key,
+            "client_access_key": self.client_access_key,
+            "client_secret_key": self.client_secret_key,
+            "state_name": self.state.name,
+            "database_type_name": self.database_type.name,
+            "targets": targets,
+            "request_quota": self.request_quota,
+            "target_quota": self.target_quota,
+        }
+
+    def get_target(self, target_id: str) -> ImageTarget:
+        """Return a target from the database with the given ID."""
+        (target,) = (
+            target for target in self.targets if target.target_id == target_id
+        )
+        return target
+
+    @classmethod
+    def from_dict(cls, database_dict: CloudDatabaseDict) -> Self:
+        """Load a database from a dictionary."""
+        targets: set[ImageTarget] = {
+            ImageTarget.from_dict(target_dict=target_dict)
+            for target_dict in database_dict["targets"]
+        }
+
+        return cls(
+            database_name=database_dict["database_name"],
+            server_access_key=database_dict["server_access_key"],
+            server_secret_key=database_dict["server_secret_key"],
+            client_access_key=database_dict["client_access_key"],
+            client_secret_key=database_dict["client_secret_key"],
+            state=States[database_dict["state_name"]],
+            database_type=DatabaseType[database_dict["database_type_name"]],
+            targets=targets,
+            request_quota=database_dict.get("request_quota", 100000),
+            target_quota=database_dict.get("target_quota", 1000),
+        )
+
+    @property
+    def not_deleted_targets(self) -> set[ImageTarget]:
+        """All targets which have not been deleted."""
+        return {target for target in self.targets if not target.delete_date}
+
+    @property
+    def active_targets(self) -> set[ImageTarget]:
+        """All active targets."""
+        return {
+            target
+            for target in self.not_deleted_targets
+            if target.status == TargetStatuses.SUCCESS.value
+            and target.active_flag
+        }
+
+    @property
+    def inactive_targets(self) -> set[ImageTarget]:
+        """All inactive targets."""
+        return {
+            target
+            for target in self.not_deleted_targets
+            if target.status == TargetStatuses.SUCCESS.value
+            and not target.active_flag
+        }
+
+    @property
+    def failed_targets(self) -> set[ImageTarget]:
+        """All failed targets."""
+        return {
+            target
+            for target in self.not_deleted_targets
+            if target.status == TargetStatuses.FAILED.value
+        }
+
+    @property
+    def processing_targets(self) -> set[ImageTarget]:
+        """All processing targets."""
+        return {
+            target
+            for target in self.not_deleted_targets
+            if target.status == TargetStatuses.PROCESSING.value
+        }
+
+
+@beartype
+@dataclass(eq=True, frozen=True, kw_only=True)
+class VuMarkDatabase:
+    """Credentials for the VuMark generation API.
+
+    Args:
+        database_name: The name of a VWS target manager database name. Defaults
+            to a random string.
+        server_access_key: A VWS server access key. Defaults to a random
+            string.
+        server_secret_key: A VWS server secret key. Defaults to a random
+            string.
+    """
+
+    database_name: str = field(default_factory=_random_hex, repr=False)
+    server_access_key: str = field(default_factory=_random_hex, repr=False)
+    server_secret_key: str = field(default_factory=_random_hex, repr=False)
+    # We have ``vumark_targets`` as ``hash=False`` so that we can have the
+    # class as ``frozen=True`` while still being able to keep the interface
+    # we want.
+    vumark_targets: set[VuMarkTarget] = field(
+        default_factory=set[VuMarkTarget],
+        hash=False,
+    )
+    state: States = States.WORKING
+
+    def get_vumark_target(self, target_id: str) -> VuMarkTarget:
+        """Return a VuMark target from the database with the given ID."""
+        (target,) = (
+            target
+            for target in self.vumark_targets
+            if target.target_id == target_id
+        )
+        return target
+
+    def to_dict(self) -> VuMarkDatabaseDict:
+        """Dump a VuMark database to a dictionary which can be loaded as
+        JSON.
+        """
+        vumark_targets = [target.to_dict() for target in self.vumark_targets]
+        return {
+            "database_name": self.database_name,
+            "server_access_key": self.server_access_key,
+            "server_secret_key": self.server_secret_key,
+            "vumark_targets": vumark_targets,
+            "state_name": self.state.name,
+        }
+
+    @classmethod
+    def from_dict(cls, database_dict: VuMarkDatabaseDict) -> Self:
+        """Load a VuMark database from a dictionary."""
+        return cls(
+            database_name=database_dict["database_name"],
+            server_access_key=database_dict["server_access_key"],
+            server_secret_key=database_dict["server_secret_key"],
+            vumark_targets={
+                VuMarkTarget.from_dict(target_dict=target_dict)
+                for target_dict in database_dict["vumark_targets"]
+            },
+            state=States[database_dict["state_name"]],
+        )
+
+    @property
+    def not_deleted_targets(self) -> set[VuMarkTarget]:
+        """All VuMark targets."""
+        return set(self.vumark_targets)

mock_vws/database_type.py

@@ -0,0 +1,13 @@
+"""Vuforia database types."""
+
+from enum import StrEnum, auto, unique
+
+from beartype import beartype
+
+
+@beartype
+@unique
+class DatabaseType(StrEnum):
+    """Constants representing various database types."""
+
+    CLOUD_RECO = auto()

mock_vws/image_matchers.py

@@ -0,0 +1,124 @@
+"""Matchers for query and duplicate requests."""
+
+import io
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+import torch
+from beartype import beartype
+from PIL import Image
+from torchmetrics.image import (
+    StructuralSimilarityIndexMeasure,
+)
+
+
+@runtime_checkable
+class ImageMatcher(Protocol):
+    """Protocol for a matcher for query and duplicate requests."""
+
+    def __call__(
+        self,
+        first_image_content: bytes,
+        second_image_content: bytes,
+    ) -> bool:
+        """Whether one image's content matches another's closely enough.
+
+        Args:
+            first_image_content: One image's content.
+            second_image_content: Another image's content.
+        """
+        # We disable a pylint warning here because the ellipsis is required
+        # for pyright to recognize this as a protocol.
+        ...  # pylint: disable=unnecessary-ellipsis
+
+
+@beartype
+class ExactMatcher:
+    """A matcher which returns whether two images are exactly equal."""
+
+    def __call__(
+        self,
+        first_image_content: bytes,
+        second_image_content: bytes,
+    ) -> bool:
+        """Whether one image's content matches another's exactly.
+
+        Args:
+            first_image_content: One image's content.
+            second_image_content: Another image's content.
+        """
+        return bool(first_image_content == second_image_content)
+
+
+@beartype
+class StructuralSimilarityMatcher:
+    """
+    A matcher which returns whether two images are similar using
+    SSIM.
+    """
+
+    def __call__(
+        self,
+        first_image_content: bytes,
+        second_image_content: bytes,
+    ) -> bool:
+        """Whether one image's content matches another's using a SSIM.
+
+        Args:
+            first_image_content: One image's content.
+            second_image_content: Another image's content.
+        """
+        first_image_file = io.BytesIO(initial_bytes=first_image_content)
+        second_image_file = io.BytesIO(initial_bytes=second_image_content)
+        with (
+            Image.open(fp=first_image_file) as first_image,
+            Image.open(fp=second_image_file) as second_image,
+        ):
+            # Images must be the same size, and they must be larger than the
+            # default SSIM window size of 11x11.
+            target_size = (256, 256)
+            first_image_resized = first_image.resize(size=target_size)
+            second_image_resized = second_image.resize(size=target_size)
+
+        first_image_np = np.array(object=first_image_resized, dtype=np.float32)
+        first_image_tensor = torch.tensor(data=first_image_np).float() / 255
+        first_image_tensor = first_image_tensor.view(
+            first_image_resized.size[1],
+            first_image_resized.size[0],
+            len(first_image_resized.getbands()),
+        )
+
+        second_image_np = np.array(
+            object=second_image_resized,
+            dtype=np.float32,
+        )
+        second_image_tensor = torch.tensor(data=second_image_np).float() / 255
+        second_image_tensor = second_image_tensor.view(
+            second_image_resized.size[1],
+            second_image_resized.size[0],
+            len(second_image_resized.getbands()),
+        )
+
+        first_image_tensor_batch_dimension = first_image_tensor.permute(
+            2,
+            0,
+            1,
+        ).unsqueeze(dim=0)
+        second_image_tensor_batch_dimension = second_image_tensor.permute(
+            2,
+            0,
+            1,
+        ).unsqueeze(dim=0)
+
+        ssim = StructuralSimilarityIndexMeasure(data_range=1.0)
+        ssim_value = ssim(
+            first_image_tensor_batch_dimension,
+            second_image_tensor_batch_dimension,
+        )
+        ssim_score = ssim_value.item()
+
+        # Normalize SSIM score from -1 to 1 scale to 0 to 10 scale.
+        # This maps -1 to 0 and 1 to 10.
+        normalized_score = (ssim_score + 1) * 5
+        minimum_acceptable_ssim_score = 7
+        return bool(normalized_score > minimum_acceptable_ssim_score)

mock_vws/model_target.py

@@ -0,0 +1,79 @@
+"""Model Target dataset objects."""
+
+import datetime
+import uuid
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from beartype import beartype
+
+
+@beartype
+class ModelTargetDatasetType(StrEnum):
+    """The kind of Model Target dataset."""
+
+    STANDARD = "standard"
+    ADVANCED = "advanced"
+
+
+@beartype
+def _now() -> datetime.datetime:
+    """Return the current time in UTC."""
+    return datetime.datetime.now(tz=ZoneInfo(key="UTC"))
+
+
+@beartype
+def _format_datetime(value: datetime.datetime) -> str:
+    """Format a timestamp like the Model Target Web API."""
+    return value.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class ModelTargetDataset:
+    """A Model Target dataset generation request.
+
+    Args:
+        request_body: The JSON request body used to start dataset creation.
+        dataset_type: Whether this is a standard or advanced dataset.
+        processing_time_seconds: The number of seconds before the generated
+            dataset becomes available.
+        uuid_: The dataset UUID.
+        created_at: When the dataset creation was requested.
+    """
+
+    request_body: dict[str, Any] = field(hash=False)
+    dataset_type: ModelTargetDatasetType
+    processing_time_seconds: float = field(hash=False)
+    uuid_: str = field(default_factory=lambda: uuid.uuid4().hex)
+    created_at: datetime.datetime = field(default_factory=_now)
+
+    @property
+    def completed_at(self) -> datetime.datetime:
+        """When the dataset completes processing."""
+        return self.created_at + datetime.timedelta(
+            seconds=self.processing_time_seconds,
+        )
+
+    @property
+    def status(self) -> str:
+        """The current dataset generation status."""
+        if _now() < self.completed_at:
+            return "processing"
+        return "done"
+
+    def status_body(self) -> dict[str, Any]:
+        """Return a status response body for this dataset."""
+        body: dict[str, Any] = {
+            "status": self.status,
+            "uuid": self.uuid_,
+            "createdAt": _format_datetime(value=self.created_at),
+        }
+        if self.status == "processing":
+            body["eta"] = _format_datetime(value=self.completed_at)
+        else:
+            body["completedAt"] = _format_datetime(value=self.completed_at)
+
+        return body

mock_vws/states.py

@@ -0,0 +1,20 @@
+"""Vuforia database states."""
+
+from enum import StrEnum, auto, unique
+
+from beartype import beartype
+
+
+@beartype
+@unique
+class States(StrEnum):
+    """Constants representing various web service states."""
+
+    WORKING = auto()
+
+    PROJECT_SUSPENDED = auto()
+
+    # A project is inactive if the license key has been deleted.
+    PROJECT_INACTIVE = auto()
+
+    PROJECT_HAS_NO_API_ACCESS = auto()