auto-trainer-core 2.0.1.dev353__py3-none-any.whl

autotrainer/core/message/system_status_message.py

@@ -0,0 +1,112 @@
+from enum import IntEnum
+from typing import Protocol
+
+
+class SystemStatusMessageKind(IntEnum):
+    """
+    This class defines the messages types that are sent by the device.  If there is a request/command that generates
+    a response, the command will be defined in the SystemCommandKind class.
+
+    A message type is sent to the caller with an optional context/data value.  This value is dependent on the message
+    type.
+
+    This is implemented and represented in the send_message() method in the DeviceApi class.
+    """
+
+    ACKNOWLEDGE = 1
+    """
+    This message should be send when a command completes along with the context that is provided with the command.  It
+    should not be sent with status messages that are generated independently by the hardware.  The is the mechanism by
+    which callers determine if and when specific commands are completed.
+    """
+
+    FIRMWARE_VERSION = 101
+    """Message will contain the firmware version of the device as a string."""
+    # TODO: This needs to be more complex than a string now that different modules are part of the same device and
+    #  connection.
+
+    PELLET_MOTOR_X = 201
+    """Message will contain the pellet X motor status as a StepperStatusMessage."""
+
+    PELLET_MOTOR_Y = 202
+    """Message will contain the pellet Y motor status as a StepperStatusMessage."""
+
+    PELLET_MOTOR_Z = 203
+    """Message will contain the pellet Z motor status as a StepperStatusMessage."""
+
+    PELLET_LOAD = 204
+    """Message will contain the pellet load arm servo status as a ServoStatusMessage."""
+
+    PELLET_COVER = 205
+    """Message will contain the pellet cover arm servo status as a ServoStatusMessage."""
+
+    HEAD_MAGNET = 206
+    """Message will contain the head fixation magnet servo status as a ServoStatusMessage."""
+
+    TUNNEL_GATE_SERVO = 207
+    """Message will contain the tunnel gate servo status as a ServoStatusMessage."""
+
+    PELLET_X = 208
+    """Message will contain the pellet X motor position as a float."""
+
+    PELLET_Y = 209
+    """Message will contain the pellet Y motor position as a float."""
+
+    PELLET_Z = 210
+    """Message will contain the pellet Z motor position as a float."""
+
+    FRONT_DOOR = 301
+    """Message will contain front door status as True (open) or False (closed)."""
+
+    DRAWER_DOOR = 302
+    """Message will contain drawer door status as True (open) or False (closed)."""
+
+    SPARE_DOOR = 303
+    """Message will contain spare door status as True (open) or False (closed)."""
+
+    EXT_BUTTON = 304
+    """Message will contain external button status as True (pressed) or False (released)"""
+
+    STIMULUS_INPUTS = 305
+    """Message will contain a list of 4 states as True/False"""
+
+    TUNNEL_FAN = 220
+    """Tunnel Fan will contain the tunnel fan status as a ServoStatusMessage"""
+
+    MEASUREMENTS = 401
+    """Message will contain a list of MeasurementMessage objects."""
+
+    AUDIO_SPECTRUM = 402
+    """Message will contain the audio spectrum data as an array list of float values."""
+
+    MOTOR_CONFIGURATION = 501
+
+    CAMERA_STATUS_CHANGE = 1001
+
+    MEASUREMENT = -101
+    """This value is deprecated.  Use MEASUREMENTS if the object you are passing with this identifier conforms to the
+    MeasurementMessage protocol."""
+
+
+class StepperStatusMessage(Protocol):
+    @property
+    def position(self) -> float:
+        """Current motor position in mm."""
+
+    @property
+    def send_position(self) -> float:
+        """Current motor delivery position in mm."""
+
+    @property
+    def is_at_limit(self) -> bool:
+        """True if the limit switch has been hit, otherwise False."""
+
+
+class ServoStatusMessage(Protocol):
+    @property
+    def location(self) -> float:
+        """Current servo position in degrees."""
+
+    @property
+    def status(self) -> int:
+        """Current servo status value."""

autotrainer/core/multiproc.py

@@ -0,0 +1,50 @@
+import logging.config
+import multiprocessing
+import signal
+import threading
+
+
+def get_mp_ctx():
+    return multiprocessing.get_context("spawn")
+
+
+class EmptyWithContext:
+
+    def __enter__(self):
+        pass
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+
+class DaemonTimer(threading.Timer):
+    """A Timer that does not block main process exit"""
+
+    finished: threading.Event
+
+    def __init__(self, delay, func, args=None, kwargs=None):
+        super().__init__(delay, func, args=args, kwargs=kwargs)
+        self.daemon = True
+
+
+def make_daemon_timer(delay, func, *args, **kwargs):
+    return DaemonTimer(delay, func, *args, **kwargs)
+
+
+def pool_init(log_dict_cfg=None):
+    """For process pool"""
+    # this is to prevent keyboard interrupted being delivered to all child processes of the main process:
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    # given by default this is what is done.
+    # inner-import on purpose: prevent import loop:
+    from autotrainer.core.logging import setup_logging, install_log_exception_hook
+    if log_dict_cfg is None:
+        setup_logging()
+    else:
+        logging.config.dictConfig(log_dict_cfg)
+        install_log_exception_hook()
+    logging.root.info("Initialized pool worker")
+
+
+no_op_timer = make_daemon_timer(0, lambda: None)
+no_op_timer.finished.set()

autotrainer/core/notification/__init__.py

@@ -0,0 +1,2 @@
+from .notification_center import NotificationCenter, Notification
+from .trigger_notification import TriggerNotification, post_trigger_enable

autotrainer/core/notification/notification_center.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Dict, List, TypeVar
+
+from typing_extensions import Self
+
+
+@dataclass(frozen=True)
+class Notification:
+    """
+    A class representing a notification with a type and optional source and context objects.
+    """
+    event_type: Any
+    """
+    The type of the event. This is used to identify the event and determine which observers should be notified.
+    """
+    source: Optional[Any] = None
+    """
+    The source of the event. This is typically the object that generated the event.
+    """
+    context: Optional[Any] = None
+
+
+TCallable = TypeVar("TCallable", bound=Callable[[Notification], None])
+
+
+class NotificationCenter:
+    """
+    A publish and subscribe implementation for general message passing where publishers can remain unaware of if there
+    are listeners and who they are.
+
+    Each process has a default notification center.  Additional instances may be created to organize notifications in
+    specific contexts.
+    """
+
+    @classmethod
+    def default_center(cls) -> Self:
+        """
+        Returns the default instance of NotificationCenter.
+        """
+        if not hasattr(cls, "_default_center"):
+            cls._default_center = cls()
+
+        return cls._default_center
+
+    def __init__(self):
+        self._subscribers: Dict[str, List[TCallable]] = {}
+
+    def add_observer(self, event_type: Any, callback: TCallable):
+        """
+        Subscribe to a specific event type with a callback function.
+        """
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+
+        if callback not in self._subscribers[event_type]:
+            self._subscribers[event_type].append(callback)
+
+    def remove_observer(self, event_type: Any, callback: TCallable):
+        """
+        Unsubscribe from a specific event type.
+        """
+        if event_type in self._subscribers:
+            if callback in self._subscribers[event_type]:
+                self._subscribers[event_type].remove(callback)
+
+    def post_notification(self, **kwargs):
+        """
+        Notify all subscribers of a specific event type.
+        """
+        if "notification" in kwargs:
+            notification = kwargs["notification"]
+            assert isinstance(notification, Notification), "notification must be of type Notification"
+        else:
+            event_type = kwargs["event_type"]
+            assert event_type is not None, "event_type must not be None"
+            notification = Notification(event_type, kwargs.get("source"), kwargs.get("context"))
+
+        if notification.event_type in self._subscribers:
+            for callback in self._subscribers[notification.event_type]:
+                callback(notification)

autotrainer/core/notification/trigger_notification.py

@@ -0,0 +1,27 @@
+from enum import Enum
+from typing import Any
+
+from .notification_center import NotificationCenter, Notification
+
+
+class TriggerNotification(Enum):
+    CAPTURE_ID = "TriggerNotificationCaptureId"
+
+
+# Convenience methods
+
+def post_trigger_enable(sender: Any, enabled: bool):
+    """
+    Post a trigger enable notification.
+
+    Args:
+        sender: The sender of the notification.
+        enabled: Whether the trigger is enabled or not.
+    """
+    NotificationCenter.default_center().post_notification(
+        notification=Notification(
+            event_type=TriggerNotification.CAPTURE_ID,
+            source=sender,
+            context=enabled
+        )
+    )

autotrainer/core/observable_object.py

@@ -0,0 +1,105 @@
+import os
+from typing import Protocol, Callable, Any, TypeVar
+from typing_extensions import Self
+
+import verboselogs
+from events import Events
+
+from autotrainer.core.logging import get_verbose_logger
+
+logger = get_verbose_logger(__name__)
+
+
+_debug_properties_change = {
+    v.strip() for v in os.getenv("AUTOTRAINER_DEBUG_PROPERTIES", "").split(",")
+}
+
+
+HandlerT = TypeVar("HandlerT", bound=Callable[..., None])
+
+AnyNewValue = Any
+AnyOldValue = Any
+
+
+class EventHandler(Protocol[HandlerT]):
+    """Single event handler"""
+
+    __call__: HandlerT
+
+    def __iadd__(self, handler: HandlerT) -> Self:
+        """Register event handler"""
+
+    def __isub__(self, handler: HandlerT) -> Self:
+        """Unregister event handler"""
+
+
+class ObservableObjectProtocol(Protocol):
+    """Allow classes that do not inherit from ObservableObject to indicate they support the property_changed event."""
+
+    property_changed: EventHandler[Callable[[str, AnyNewValue, AnyOldValue], None]]
+
+
+class ObservableObject(Events):
+    """
+    Defines a class with observable property change events.  This is a common pattern for UI frameworks in
+    particular where some form of a view layer and some type of model layer need to communicate changes in a decoupled
+    way.  However, it is applicable in many other situations as well.
+
+    The property_changed event is used by one or more listeners to respond to property changes.
+
+    _on_property_changed is a convenience method that will only generate an event if the new value does not pass
+    the == test with the old value.  This prevents needless events and more importantly endless recursion when two
+    objects are listening to each other to stay in sync (e.g., UI and model where a change may originate in either).
+    """
+
+    # type hint for dynamic event function (added by Events):
+    property_changed: EventHandler[Callable[[str, AnyNewValue, AnyOldValue], None]]
+
+    def __init__(self, event_names=()):
+        super().__init__(event_names + ("property_changed",))
+
+    # def __bool__(self):
+    #     # NB: was used to make the `if model:` in Machine.__init__ method works,
+    #     # when tried mixing an ObservableObject with transitions.Machine
+    #     # but there were other issues too, so keeping commented, as ref. at worst.
+    #     # NB2: this is because the __bool__ method is otherwise overridden by the Events.__len__ method
+    #     #  which returns the nbr of events handled by the given instance.
+    #     return True
+
+    def _on_property_changed(self, name: str, new_value: AnyNewValue, old_value: AnyOldValue):
+        """
+        Generate a property-changed event if the new value does not pass the == test with the old value.
+
+        This is a convenience method for only generating an event when the value has actually changed (as defined by
+        `==`).  If `==` is not an appropriate test for a given property, a subclass should override this method for
+        handling that property, or the caller should use the property_changed event directly.
+
+        A common pattern for subclasses would be:
+
+        ```
+        def set_age(self, value: int):
+            prev, self._age = self._age, value  # assign the value before call the _on_property_changed event
+            self._on_property_changed("age", value, prev)
+        ```
+
+        This will only generate an event if the new value is different from the old value and update the member variable
+        with the new value if it changed.
+
+        An important note for event handlers is that the property on the object will be the old value at the time the
+        event is handled.  Handlers must use the `new_value` argument to get the new value.
+
+        Args:
+            name (str): Name of the property that changed.
+            new_value: New value of the property.
+            old_value: Old/current value of the property.
+        """
+        if old_value == new_value:
+            return old_value
+
+        if __debug__:
+            if name in _debug_properties_change:
+                logger.debug("%s: property %r: from %s to %s", self, name, old_value, new_value,
+                             stack_info=logger.level == verboselogs.SPAM)
+
+        self.property_changed(name, new_value, old_value)
+        return new_value

autotrainer/core/perf_monitor.py

@@ -0,0 +1,77 @@
+import logging
+import time
+from dataclasses import dataclass, field
+from math import floor
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PerfMonitor:
+    """
+    Convenience class to measure and report performance metrics.  There are likely more robust or feature complete
+    packages available.  This is intended as a simple implementation to not add to the dependency list of the project.
+
+    The monitor tracks `cycles` or number of times something happens.  What this means is defined by the caller.
+    """
+    name: str = ""
+    """User-friendly name for the performance monitor."""
+    units: str = ""
+    """Units for the performance monitor."""
+    report_window: int = 15
+    """Duration between each report"""
+    enable_log: bool = True
+    """Allow toggling reporting while running."""
+    log_level: int = logging.DEBUG
+    """Log level for reporting performance metrics."""
+    cps: float = 0.0
+    """Most recent cycles per second (CPS) value."""
+
+    _cycle_count: Optional[int] = field(default=None, init=False, repr=False, compare=False)
+    _start: float = field(default=0, init=False, repr=False, compare=False)
+    _next_refresh: float = field(default=0, init=False, repr=False, compare=False)
+
+    def reset(self):
+        """
+        Resets all cycle counts and timing.  Calculations will resume on the next `add_cycle` or `add_cycles` call.
+        """
+        logger.debug("%s: reset", self.name)
+        self._cycle_count = None
+
+    def add_cycle(self) -> bool:
+        """
+        Add a single cycle to the count.
+
+        Returns:
+            bool: True if the CPS value was reported. False otherwise.
+        """
+        return self.add_cycles(1)
+
+    def add_cycles(self, cycles: int) -> bool:
+        """
+        Add a block of cycles to the count.
+
+        Returns:
+            bool: True if the CPS value was reported. False otherwise.
+        """
+        if cycles <= 0:
+            return False
+
+        t_perf_now = time.perf_counter()
+
+        if self._cycle_count is None:
+            self._cycle_count = 0
+            self._next_refresh = self._start = t_perf_now
+            self._next_refresh += self.report_window
+
+        elif t_perf_now > self._next_refresh:
+            self.cps = self._cycle_count / (t_perf_now - self._next_refresh + self.report_window)
+            if self.enable_log:
+                logger.log(self.log_level, f"{self.name}: {self.cps:.1f} {self.units}")
+            self._next_refresh += self.report_window
+            self._cycle_count = cycles
+            return True
+
+        self._cycle_count += cycles
+        return False

autotrainer/core/pose_elements.py

@@ -0,0 +1,196 @@
+
+import dataclasses
+import math
+from enum import Enum
+from typing import Dict, Optional
+
+from autotrainer.core import get_perf_now
+
+_cache_scene_elements: Dict[str, "_BaseSceneElement"] = {}
+_cache_scene_elements_str: Dict[str, str] = {}
+
+
+class _BaseSceneElement(str):  # , Enum):
+    """Dedicated str subclass for scene elements,
+    main feature is to have the created elements be all cached/singleton,
+    allowing use of "is" operator comparison with previous reference to any of them.
+    """
+    # we might want to use something more flexible, if the model would not use same names than here,
+    # like with a mapping dict, and some dynamic attributes + type hints on the class to still help development.
+
+    @classmethod
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        # set all string values to SceneElement/cls instance,
+        # which pre-loads it in _cache_scene_elements:
+        for name, value in vars(cls).items():
+            if cls.__annotations__.get(name) != 'SceneElement' or not isinstance(value, str):
+                continue
+            setattr(cls, name, cls(value))
+
+    def __new__(cls, value: str):
+        cached = _cache_scene_elements.get(value, None)
+        if cached is None:
+            tentative = super().__new__(cls, value)
+            assert isinstance(tentative, _BaseSceneElement)
+            cached = _cache_scene_elements.setdefault(value, tentative)  # threads-safe
+        # return the raw str value:
+        # otherwise, when used as column(multiindex or not) and in h5 files that will make
+        # the column to be saved with pickle,
+        # which when unpickled fails if the pickled object type has been moved meanwhile.
+        cached_str = _cache_scene_elements_str.setdefault(value, str(cached))
+        return cached_str
+
+
+class SceneElement(_BaseSceneElement):
+
+    Pellet: "SceneElement" = 'Pellet'
+
+    R_Hand: "SceneElement" = 'R_Hand'  # composite element part
+    RH_flat: "SceneElement" = 'RH_flat'
+    RH_spread: "SceneElement" = 'RH_spread'
+    RH_grab: "SceneElement" = 'RH_grab'
+
+    L_Hand: "SceneElement" = 'L_Hand'  # composite element part
+    LH_flat: "SceneElement" = 'LH_flat'
+    LH_spread: "SceneElement" = 'LH_spread'
+    LH_grab: "SceneElement" = 'LH_grab'
+
+    Nose: "SceneElement" = 'Nose'
+    Mouth: "SceneElement" = 'Mouth'
+    Tongue_mid: "SceneElement" = 'Tongue_mid'
+    Tongue_tip: "SceneElement" = 'Tongue_tip'
+
+    Star: "SceneElement" = 'Star'
+    Diamond: "SceneElement" = 'Diamond'
+    Triangle: "SceneElement" = 'Triangle'
+
+    AnyAnimalPart: "SceneElement" = 'AnyAnimalPart'
+
+
+AllHandsParts = {
+    SceneElement.RH_flat, SceneElement.RH_spread, SceneElement.RH_grab,
+    SceneElement.LH_flat, SceneElement.LH_spread, SceneElement.LH_grab,
+}
+
+
+AllAnimalParts = {
+    SceneElement.Nose,
+    SceneElement.Mouth,
+    SceneElement.Tongue_tip,
+    SceneElement.Tongue_mid,
+} | AllHandsParts
+
+
+AllNonAnimalParts = {
+    SceneElement.Pellet,
+    SceneElement.Diamond,
+    SceneElement.Triangle,
+    SceneElement.Star,
+}
+
+
+AllSceneParts = AllAnimalParts | AllNonAnimalParts
+
+
+@dataclasses.dataclass
+class ScenePartsPresenceContext:
+    """Maintain a context of presence/absence status & age of parts/elements"""
+
+    # TODO: for now only considering presence in either of the 2 possible cameras,
+    #  but we could handle 3 cases of presence/absence:
+    #   1) on any of the possible cams
+    #       > can be/is used for checking pellet presence at the end of load sequence
+    #   2) on all of the possible cams simultaneously
+    #       > should be used to report pellet successfully loaded (more reliably)
+    #   3) on all of the possible cams non-simultaneously
+    #       > not entirely sure could be useful if we have already 1 + 2
+
+    last_perf_c: float = -math.inf  # last perf counter received, basically the "freshness" of the data
+
+    present_last_perf_c: Dict[str, float] = dataclasses.field(default_factory=dict)
+    missing_last_perf_c: Dict[str, float] = dataclasses.field(default_factory=dict)
+
+    def get_part_seen(self, part: str) -> bool:
+        """Say if the part was seen on last update"""
+        p_present = self.present_last_perf_c.get(part, -math.inf)
+        p_missing = self.missing_last_perf_c.get(part, -math.inf)
+        if math.isinf(p_present):
+            return p_present > 0
+        return p_present > p_missing
+
+    def get_presence_age(self, part: str, *, perf_now: Optional[float] = None) -> float:
+        """Returns the "presence age" of the part if it's currently present, otherwise -math.inf"""
+        if perf_now is None:
+            perf_now = self.last_perf_c
+        presence_p = self.present_last_perf_c.get(part, None)
+        if presence_p is None:
+            return -math.inf
+        return perf_now - presence_p
+
+    def get_absence_age(self, part: str, *, perf_now: Optional[float] = None) -> float:
+        """Returns the "absence age" of the part if it's currently absent, otherwise -math.inf.
+        Age can also be math.inf if never seen yet"""
+        if perf_now is None:
+            perf_now = self.last_perf_c
+        presence_p = self.present_last_perf_c.get(part, None)
+        absence_p = self.missing_last_perf_c.get(part, None)
+        if absence_p is None:
+            return math.inf if presence_p is None else -math.inf
+        if presence_p is not None and presence_p > absence_p:
+            return -math.inf
+        return perf_now - absence_p
+
+    def get_recently_seen(self, part: str, missing_delay: float, *, perf_now: Optional[float] = None) -> bool:
+        """Returns if part was seen before missing_delay, relatively to perf_now, or self.last_perf_c"""
+        if perf_now is None:
+            perf_now = self.last_perf_c
+        prev_miss = self.missing_last_perf_c.get(part, -math.inf)
+        prev_pres = self.present_last_perf_c.get(part, -math.inf)
+        return (
+            not math.isinf(prev_pres)
+            and (prev_pres > prev_miss or perf_now - prev_miss < missing_delay)
+        )
+
+    def update_part_seen(self, part: str, seen: bool, *, perf_now: Optional[float] = None):
+        if perf_now is None:
+            perf_now = get_perf_now()
+        prev_seen = self.present_last_perf_c.get(part, -math.inf)
+        prev_miss = self.missing_last_perf_c.get(part, -math.inf)
+        if seen:
+            if prev_seen < prev_miss or math.isinf(prev_seen):
+                self.present_last_perf_c[part] = perf_now
+                self.missing_last_perf_c.setdefault(part, -math.inf)
+        else:
+            if prev_miss < prev_seen or math.isinf(prev_miss):
+                self.missing_last_perf_c[part] = perf_now
+                self.present_last_perf_c.setdefault(part, -math.inf)
+        if perf_now > self.last_perf_c:
+            self.last_perf_c = perf_now
+
+    def get_animal_absence_age(self, *, perf_now: Optional[float] = None):
+        """Returns the animal "absence" age, how old/elapsed time since last absence started,
+        can be math.inf if never been absent"""
+        if perf_now is None:
+            perf_now = get_perf_now()
+        max_perf_c = -math.inf
+        parts = set(self.missing_last_perf_c) | set(self.present_last_perf_c)
+        for part in parts:
+            if part in AllAnimalParts:
+                perf_c = self.missing_last_perf_c.get(part, -math.inf)
+                if perf_c > max_perf_c:
+                    max_perf_c = perf_c
+        return perf_now - max_perf_c
+
+    def get_animal_presence_age(self, *, perf_now: Optional[float] = None):
+        """Returns the animal most recent "presence" age. ie: how old since it has been seen last time"""
+        if perf_now is None:
+            perf_now = get_perf_now()
+        max_perf_c = -math.inf
+        parts = set(self.missing_last_perf_c) | set(self.present_last_perf_c)
+        for part in parts:
+            if part in AllAnimalParts:
+                perf_c = self.present_last_perf_c.get(part, -math.inf)
+                if perf_c > max_perf_c:
+                    max_perf_c = perf_c
+        return perf_now - max_perf_c

autotrainer/core/project/__init__.py

@@ -0,0 +1,19 @@
+from typing import Protocol
+
+from .project_info import ProjectInfo
+from .project_info import ProjectInterval
+from .project_info import video_write_ext
+
+
+class ProjectDependentProtocol(Protocol):
+
+    @property
+    def project(self) -> ProjectInfo:
+        """The associated current project-info"""
+
+    @project.setter
+    def project(self, value: ProjectInfo):
+        """Project-info setter"""
+
+
+ProjectDependentProtol = ProjectDependentProtocol  # previous typo alias