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

mock_vws/target.py

@@ -0,0 +1,285 @@
+"""A fake implementation of a target for the Vuforia Web Services API."""
+
+import base64
+import datetime
+import io
+import statistics
+import uuid
+from dataclasses import dataclass, field
+from typing import Self, TypedDict
+from zoneinfo import ZoneInfo
+
+from beartype import BeartypeConf, beartype
+from PIL import Image, ImageStat
+
+from mock_vws._constants import TargetStatuses
+from mock_vws.target_raters import (
+    HardcodedTargetTrackingRater,
+    TargetTrackingRater,
+)
+
+
+class VuMarkTargetDict(TypedDict):
+    """A dictionary type which represents a VuMark target."""
+
+    target_id: str
+    name: str
+    processing_time_seconds: float
+    last_modified_date: str
+    upload_date: str
+
+
+class ImageTargetDict(TypedDict):
+    """A dictionary type which represents an image target."""
+
+    name: str
+    width: float
+    image_base64: str
+    active_flag: bool
+    processing_time_seconds: float
+    application_metadata: str | None
+    target_id: str
+    last_modified_date: str
+    delete_date_optional: str | None
+    upload_date: str
+    tracking_rating: int
+
+
+@beartype
+def _random_hex() -> str:
+    """Return a random hex value."""
+    return uuid.uuid4().hex
+
+
+@beartype
+def _time_now() -> datetime.datetime:
+    """Return the current time in the GMT time zone."""
+    gmt = ZoneInfo(key="GMT")
+    return datetime.datetime.now(tz=gmt)
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+@dataclass(frozen=True, eq=True, kw_only=True)
+class ImageTarget:
+    """A Vuforia image target as managed in
+    https://developer.vuforia.com/target-manager.
+    """
+
+    active_flag: bool
+    application_metadata: str | None
+    image_value: bytes
+    name: str
+    processing_time_seconds: float
+    width: float
+    target_tracking_rater: TargetTrackingRater = field(compare=False)
+    current_month_recos: int = 0
+    delete_date: datetime.datetime | None = None
+    last_modified_date: datetime.datetime = field(default_factory=_time_now)
+    previous_month_recos: int = 0
+    reco_rating: str = ""
+    target_id: str = field(default_factory=_random_hex)
+    total_recos: int = 0
+    upload_date: datetime.datetime = field(default_factory=_time_now)
+
+    @property
+    def _post_processing_status(self) -> TargetStatuses:
+        """Return the status of the target, or what it will be when
+        processing
+        is finished.
+
+        The status depends on the standard deviation of the color bands.
+        How VWS determines this is unknown, but it relates to how
+        suitable the target is for detection.
+        """
+        image_file = io.BytesIO(initial_bytes=self.image_value)
+        with Image.open(fp=image_file) as image:
+            image_stat = ImageStat.Stat(image_or_list=image)
+            average_std_dev = statistics.mean(data=image_stat.stddev)
+
+        success_threshold = 5
+
+        if average_std_dev > success_threshold:
+            return TargetStatuses.SUCCESS
+
+        return TargetStatuses.FAILED
+
+    @property
+    def status(self) -> str:
+        """Return the status of the target.
+
+        For now this waits half a second (arbitrary) before changing the
+        status from 'processing' to 'failed' or 'success'.
+
+        The status depends on the standard deviation of the color bands.
+        How VWS determines this is unknown, but it relates to how
+        suitable the target is for detection.
+        """
+        processing_time = datetime.timedelta(
+            seconds=float(self.processing_time_seconds),
+        )
+
+        timezone = self.upload_date.tzinfo
+        now = datetime.datetime.now(tz=timezone)
+        time_since_change = now - self.last_modified_date
+
+        if time_since_change <= processing_time:
+            return TargetStatuses.PROCESSING.value
+
+        return self._post_processing_status.value
+
+    @property
+    def _post_processing_target_rating(self) -> int:
+        """The rating of the target after processing."""
+        return self.target_tracking_rater(image_content=self.image_value)
+
+    @property
+    def tracking_rating(self) -> int:
+        """Return the tracking rating of the target recognition image."""
+        pre_rating_time = datetime.timedelta(
+            # That this is half of the total processing time is unrealistic.
+            # In VWS it is not a constant percentage.
+            seconds=float(self.processing_time_seconds) / 2,
+        )
+
+        timezone = self.upload_date.tzinfo
+        now = datetime.datetime.now(tz=timezone)
+        time_since_upload = now - self.upload_date
+
+        # The real VWS seems to give -1 for a short time while processing, then
+        # the real rating, even while it is still processing.
+        if time_since_upload <= pre_rating_time:
+            return -1
+
+        return self._post_processing_target_rating
+
+    @classmethod
+    def from_dict(cls, target_dict: ImageTargetDict) -> Self:
+        """Load a target from a dictionary."""
+        timezone = ZoneInfo(key="GMT")
+        name = target_dict["name"]
+        active_flag = target_dict["active_flag"]
+        width = target_dict["width"]
+        image_base64 = target_dict["image_base64"]
+        image_value = base64.b64decode(s=image_base64)
+        processing_time_seconds = target_dict["processing_time_seconds"]
+        application_metadata = target_dict["application_metadata"]
+        target_id = target_dict["target_id"]
+        delete_date_optional = target_dict["delete_date_optional"]
+        if delete_date_optional is None:
+            delete_date = None
+        else:
+            delete_date = datetime.datetime.fromisoformat(delete_date_optional)
+            delete_date = delete_date.replace(tzinfo=timezone)
+
+        last_modified_date = datetime.datetime.fromisoformat(
+            target_dict["last_modified_date"],
+        ).replace(tzinfo=timezone)
+        upload_date = datetime.datetime.fromisoformat(
+            target_dict["upload_date"],
+        ).replace(tzinfo=timezone)
+
+        target_tracking_rater = HardcodedTargetTrackingRater(
+            rating=target_dict["tracking_rating"],
+        )
+        return cls(
+            target_id=target_id,
+            name=name,
+            active_flag=active_flag,
+            width=width,
+            image_value=image_value,
+            processing_time_seconds=processing_time_seconds,
+            application_metadata=application_metadata,
+            delete_date=delete_date,
+            last_modified_date=last_modified_date,
+            upload_date=upload_date,
+            target_tracking_rater=target_tracking_rater,
+        )
+
+    def to_dict(self) -> ImageTargetDict:
+        """Dump a target to a dictionary which can be loaded as JSON."""
+        delete_date: str | None = None
+        if self.delete_date:
+            delete_date = self.delete_date.isoformat()
+
+        image_base64 = base64.encodebytes(s=self.image_value).decode()
+
+        return {
+            "name": self.name,
+            "width": self.width,
+            "image_base64": image_base64,
+            "active_flag": self.active_flag,
+            "processing_time_seconds": float(self.processing_time_seconds),
+            "application_metadata": self.application_metadata,
+            "target_id": self.target_id,
+            "last_modified_date": self.last_modified_date.isoformat(),
+            "delete_date_optional": delete_date,
+            "upload_date": self.upload_date.isoformat(),
+            "tracking_rating": self.tracking_rating,
+        }
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+@dataclass(frozen=True, eq=True, kw_only=True)
+class VuMarkTarget:
+    """
+    A VuMark target as managed in
+    https://developer.vuforia.com/target-manager.
+
+    Unlike ImageTarget, VuMark targets do not require an image — they use a
+    VuMark template.
+    """
+
+    name: str
+    processing_time_seconds: float = 0.0
+    target_id: str = field(default_factory=_random_hex)
+    last_modified_date: datetime.datetime = field(default_factory=_time_now)
+    upload_date: datetime.datetime = field(default_factory=_time_now)
+
+    @property
+    def status(self) -> str:
+        """Return the status of the target.
+
+        VuMark targets always succeed after processing.
+        """
+        processing_time = datetime.timedelta(
+            seconds=float(self.processing_time_seconds),
+        )
+
+        timezone = self.upload_date.tzinfo
+        now = datetime.datetime.now(tz=timezone)
+        time_since_change = now - self.last_modified_date
+
+        if time_since_change <= processing_time:
+            return TargetStatuses.PROCESSING.value
+
+        return TargetStatuses.SUCCESS.value
+
+    @classmethod
+    def from_dict(cls, target_dict: VuMarkTargetDict) -> Self:
+        """Load a VuMark target from a dictionary."""
+        timezone = ZoneInfo(key="GMT")
+        last_modified_date = datetime.datetime.fromisoformat(
+            target_dict["last_modified_date"],
+        ).replace(tzinfo=timezone)
+        upload_date = datetime.datetime.fromisoformat(
+            target_dict["upload_date"],
+        ).replace(tzinfo=timezone)
+        return cls(
+            target_id=target_dict["target_id"],
+            name=target_dict["name"],
+            processing_time_seconds=target_dict["processing_time_seconds"],
+            last_modified_date=last_modified_date,
+            upload_date=upload_date,
+        )
+
+    def to_dict(self) -> VuMarkTargetDict:
+        """Dump a VuMark target to a dictionary which can be loaded as
+        JSON.
+        """
+        return {
+            "target_id": self.target_id,
+            "name": self.name,
+            "processing_time_seconds": float(self.processing_time_seconds),
+            "last_modified_date": self.last_modified_date.isoformat(),
+            "upload_date": self.upload_date.isoformat(),
+        }

mock_vws/target_manager.py

@@ -0,0 +1,178 @@
+"""A fake implementation of a Vuforia target manager."""
+
+from typing import TYPE_CHECKING
+
+from beartype import beartype
+
+from mock_vws.database import CloudDatabase, VuMarkDatabase
+from mock_vws.model_target import ModelTargetDataset
+
+if TYPE_CHECKING:
+    from mock_vws._database_matchers import AnyDatabase
+
+
+@beartype
+class TargetManager:
+    """
+    A target manager.
+
+    See https://developer.vuforia.com/target-manager.
+    """
+
+    def __init__(self) -> None:
+        """Create a target manager with no databases."""
+        self._cloud_databases: set[CloudDatabase] = set()
+        self._vumark_databases: set[VuMarkDatabase] = set()
+        self._model_target_datasets: dict[str, ModelTargetDataset] = {}
+
+    @property
+    def cloud_databases(self) -> set[CloudDatabase]:
+        """All cloud databases."""
+        return set(self._cloud_databases)
+
+    @property
+    def vumark_databases(self) -> set[VuMarkDatabase]:
+        """All VuMark databases."""
+        return set(self._vumark_databases)
+
+    @property
+    def model_target_datasets(self) -> dict[str, ModelTargetDataset]:
+        """All Model Target datasets, keyed by UUID."""
+        return dict(self._model_target_datasets)
+
+    def remove_cloud_database(self, cloud_database: CloudDatabase) -> None:
+        """Remove a cloud database.
+
+        Args:
+            cloud_database: The cloud database to remove.
+
+        Raises:
+            KeyError: The cloud database is not in the target manager.
+        """
+        self._cloud_databases = {
+            db for db in self._cloud_databases if db != cloud_database
+        }
+
+    def remove_vumark_database(self, vumark_database: VuMarkDatabase) -> None:
+        """Remove a VuMark database.
+
+        Args:
+            vumark_database: The VuMark database to remove.
+        """
+        self._vumark_databases = {
+            db for db in self._vumark_databases if db != vumark_database
+        }
+
+    def add_model_target_dataset(
+        self,
+        model_target_dataset: ModelTargetDataset,
+    ) -> None:
+        """Add a Model Target dataset."""
+        self._model_target_datasets[model_target_dataset.uuid_] = (
+            model_target_dataset
+        )
+
+    def remove_model_target_dataset(self, dataset_uuid: str) -> None:
+        """Remove a Model Target dataset."""
+        del self._model_target_datasets[dataset_uuid]
+
+    def add_cloud_database(self, cloud_database: CloudDatabase) -> None:
+        """Add a cloud database.
+
+        Args:
+            cloud_database: The cloud database to add.
+
+        Raises:
+            ValueError: One of the given cloud database keys matches a key for
+                an existing cloud database.
+        """
+        message_fmt = (
+            "All {key_name}s must be unique. "
+            'There is already a database with the {key_name} "{value}".'
+        )
+        all_databases: list[AnyDatabase] = [
+            *self._cloud_databases,
+            *self._vumark_databases,
+        ]
+        for existing_db in all_databases:
+            for existing, new, key_name in (
+                (
+                    existing_db.server_access_key,
+                    cloud_database.server_access_key,
+                    "server access key",
+                ),
+                (
+                    existing_db.server_secret_key,
+                    cloud_database.server_secret_key,
+                    "server secret key",
+                ),
+                (
+                    existing_db.database_name,
+                    cloud_database.database_name,
+                    "name",
+                ),
+            ):
+                if existing == new:
+                    message = message_fmt.format(key_name=key_name, value=new)
+                    raise ValueError(message)
+
+        for existing_cloud_db in self._cloud_databases:
+            for existing, new, key_name in (
+                (
+                    existing_cloud_db.client_access_key,
+                    cloud_database.client_access_key,
+                    "client access key",
+                ),
+                (
+                    existing_cloud_db.client_secret_key,
+                    cloud_database.client_secret_key,
+                    "client secret key",
+                ),
+            ):
+                if existing == new:
+                    message = message_fmt.format(key_name=key_name, value=new)
+                    raise ValueError(message)
+
+        self._cloud_databases = {*self._cloud_databases, cloud_database}
+
+    def add_vumark_database(self, vumark_database: VuMarkDatabase) -> None:
+        """Add a VuMark database.
+
+        Args:
+            vumark_database: The VuMark database to add.
+
+        Raises:
+            ValueError: One of the given database keys matches a key for
+                an existing database.
+        """
+        message_fmt = (
+            "All {key_name}s must be unique. "
+            'There is already a database with the {key_name} "{value}".'
+        )
+        all_databases: list[AnyDatabase] = [
+            *self._cloud_databases,
+            *self._vumark_databases,
+        ]
+        for existing_db in all_databases:
+            for existing, new, key_name in (
+                (
+                    existing_db.server_access_key,
+                    vumark_database.server_access_key,
+                    "server access key",
+                ),
+                (
+                    existing_db.server_secret_key,
+                    vumark_database.server_secret_key,
+                    "server secret key",
+                ),
+                (
+                    existing_db.database_name,
+                    vumark_database.database_name,
+                    "name",
+                ),
+            ):
+                if existing == new:
+                    message = message_fmt.format(key_name=key_name, value=new)
+                    raise ValueError(message)
+
+        self._vumark_databases = {*self._vumark_databases, vumark_database}

mock_vws/target_raters.py

@@ -0,0 +1,109 @@
+"""Raters for target quality."""
+
+import functools
+import io
+import math
+import secrets
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+import torch
+from beartype import beartype
+from PIL import Image
+from piq.brisque import brisque  # pyright: ignore[reportMissingTypeStubs]
+
+
+@functools.cache
+@beartype
+def _get_brisque_target_tracking_rating(*, image_content: bytes) -> int:
+    """Get a target tracking rating based on a BRISQUE score.
+
+    This is a rough approximation of the quality score used by Vuforia, but is
+    not accurate. For example, our "corrupted_image" rating is based on a
+    BRISQUE score of 0, but Vuforia's is 1.
+
+    Args:
+        image_content: A target's image's content.
+    """
+    image_file = io.BytesIO(initial_bytes=image_content)
+    with Image.open(fp=image_file) as image:
+        image_np = np.array(object=image, dtype=np.float32)
+        image_tensor = torch.tensor(data=image_np).float() / 255
+        image_tensor = image_tensor.view(
+            image.size[1],
+            image.size[0],
+            len(image.getbands()),
+        )
+    image_tensor = image_tensor.permute(2, 0, 1).unsqueeze(dim=0)
+    try:
+        brisque_score = brisque(x=image_tensor, data_range=255)
+    except AssertionError, IndexError:
+        return 0
+    return math.ceil(int(brisque_score.item()) / 20)
+
+
+@runtime_checkable
+class TargetTrackingRater(Protocol):
+    """Protocol for a rater of target quality."""
+
+    def __call__(self, image_content: bytes) -> int:
+        """The target tracking rating.
+
+        Args:
+            image_content: A target's 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 RandomTargetTrackingRater:
+    """A rater which returns a random number."""
+
+    def __call__(self, image_content: bytes) -> int:
+        """A random target tracking rating.
+
+        Args:
+            image_content: A target's image's content.
+        """
+        del image_content
+        return secrets.randbelow(exclusive_upper_bound=6)
+
+
+@beartype
+class HardcodedTargetTrackingRater:
+    """A rater which returns a hardcoded number."""
+
+    def __init__(self, rating: int) -> None:
+        """
+        Args:
+            rating: The rating to return.
+        """
+        self._rating = rating
+
+    def __call__(self, image_content: bytes) -> int:
+        """A random target tracking rating.
+
+        Args:
+            image_content: A target's image's content.
+        """
+        del image_content
+        return self._rating
+
+
+@beartype
+class BrisqueTargetTrackingRater:
+    """A rater which returns a rating based on a BRISQUE score."""
+
+    def __call__(self, image_content: bytes) -> int:
+        """A rating based on a BRISQUE score.
+
+        This is a rough approximation of the quality score used by Vuforia, but
+        is not accurate. For example, our "corrupted_image" fixture is rated as
+        -2 by Vuforia, but is rated as 0 by this function.
+
+        Args:
+            image_content: A target's image's content.
+        """
+        return _get_brisque_target_tracking_rating(image_content=image_content)