pigeon-tem-comms 1.4.1__py3-none-any.whl → 2.1.0__py3-none-any.whl

TEM_comms/__init__.py

@@ -1,9 +1,17 @@
-from pigeon import BaseMessage
-from . import buffer, camera, montage, qc, roi, scope, stage, tile, ui, calibration
-
-
-class State(BaseMessage):
-    state: str
+from . import (
+    buffer,
+    camera,
+    montage,
+    qc,
+    roi,
+    scope,
+    stage,
+    tile,
+    ui,
+    calibration,
+    state,
+    lens_correction,
+)
 
 
 topics = {
@@ -14,6 +22,9 @@ topics = {
     "camera.status": camera.Status,
     "scope.command": scope.Command,
     "scope.status": scope.Status,
+    "scope.image_shift.status": scope.image_shift.Status,
+    "scope.image_shift.command": scope.image_shift.Command,
+    "scope.image_shift.calibrate": scope.image_shift.Calibrate,
     "stage.aperture.command": stage.aperture.Command,
     "stage.aperture.status": stage.aperture.Status,
     "stage.motion.command": stage.motion.Command,
@@ -28,6 +39,7 @@ topics = {
     "tile.statistics.histogram": tile.statistics.Histogram,
     "tile.statistics.min_max_mean": tile.statistics.MinMaxMean,
     "tile.matches": tile.Matches,
+    "tile.template_matches": tile.TemplateMatches,
     "ui.edit": ui.Edit,
     "ui.run": ui.Run,
     "ui.setup": ui.Setup,
@@ -40,5 +52,7 @@ topics = {
     "montage.minimaps": montage.Minimaps,
     "calibration.resolution": calibration.Resolution,
     "calibration.centroid": calibration.Centroid,
-    "state": State,
+    "state.current": state.Current,
+    "state.change": state.Change,
+    "lens_correction.transform": lens_correction.Transform,
 }

TEM_comms/buffer.py

@@ -1,7 +1,18 @@
 from pigeon import BaseMessage
+from pydantic import Field
 
 
 class Status(BaseMessage):
-    queue_length: int
-    free_space: int
-    upload_rate: int
+    """
+    This message contains information about the status of the tile upload buffer.
+    """
+
+    queue_length: int = Field(
+        description="The number of tiles currently stored and waiting to be uploaded."
+    )
+    free_space: int = Field(
+        description="The amount of free space on the tile storage disk in bytes."
+    )
+    upload_rate: int = Field(
+        description="The rate at which data is being uploaded in bits per second."
+    )

TEM_comms/calibration.py

@@ -1,18 +1,42 @@
 from pigeon import BaseMessage
 from typing import Mapping
+from pydantic import Field
 
 
 class _Resolution(BaseMessage):
-    nm_per_px: tuple[float, float]
-    rotation: float
+    nm_per_px: tuple[float, float] = Field(
+        description="The X-Y size of each pixel in the processed camera image in nanometers.",
+        examples=[(3.97, 4.03)],
+    )
+    rotation: float = Field(
+        description="The rotation required to match a right-handed image coordinate system to the coordinate system of the stage in radians."
+    )
 
 
 class Resolution(BaseMessage):
-    lowmag: Mapping[int, _Resolution]
-    mag: Mapping[int, _Resolution]
+    """
+    This message contains the resolutions of all the calibrated magnifications of the microscope.
+    """
+
+    lowmag: Mapping[int, _Resolution] = Field(
+        description="A mapping of calibrated low-mag magnifications to thier calibration values."
+    )
+    mag: Mapping[int, _Resolution] = Field(
+        description="A mapping of calibrated high-mag magnifications to their calibration values."
+    )
 
 
 class Centroid(BaseMessage):
-    aperture_id: int
-    x: int
-    y: int
+    """
+    This message contains the location of the centroid of the specified aperture.
+    """
+
+    aperture_id: int = Field(
+        description="The ID of the aperture that this centroid pertains to."
+    )
+    x: int = Field(
+        description="The stage coordinate system X axis location of the centroid."
+    )
+    y: int = Field(
+        description="The stage coordinate system Y axis location of the centroid."
+    )

TEM_comms/camera.py

@@ -1,34 +1,64 @@
 from pigeon import BaseMessage
-from .tile.metadata import TileMetadata
+from .tile.metadata import TileMetadata, ProcessingOptions
 from typing import Optional
+from pydantic import Field
 
 
-class Command(TileMetadata):
-    brightfield: Optional[bool] = False
-    darkfield: Optional[bool] = False
-    lens_correction: Optional[bool] = True
+class Command(TileMetadata, ProcessingOptions):
+    """
+    This message is used to instruct the camera to capture an image.
+    """
 
 
 class Image(BaseMessage):
-    tile_id: str
-    montage_id: str
+    """
+    This message is sent after the camera exposure is complete.
+    """
+
+    tile_id: str = Field(
+        description="The tile ID", examples=["69005602-15b0-4407-bf5b-4bddd6629141"]
+    )
+    montage_id: str = Field(
+        description="The montage ID. If a zero length string, the tile is for UI display or calibration purposes only.",
+        examples=["4330c7cf-e45b-4950-89cf-82dc0f815fe9"],
+    )
 
 
 class Settings(BaseMessage):
-    exposure: float | None = None
-    gain: Optional[float] = None
-    width: int | None = None
-    height: int | None = None
+    """
+    This message is used to change camera settings.
+    """
+
+    exposure: float | None = Field(
+        default=None, description="The length of the camera exposure in microseconds."
+    )
+    gain: Optional[float] = Field(
+        default=None, description="The camera gain in decibels."
+    )
+    width: int | None = Field(
+        default=None, description="The width of the camera frame."
+    )
+    height: int | None = Field(
+        default=None, description="The height of the camera frame."
+    )
 
 
 class Status(BaseMessage):
-    exposure: float
-    gain: float
-    width: int
-    height: int
-    temp: float
-    target_temp: float
-    device_name: str
-    device_model_id: int
-    device_sn: str
-    bit_depth: int | str
+    """
+    This message contains information about the state of the camera.
+    """
+
+    exposure: float = Field(
+        description="The length of the camera exposure in microseconds."
+    )
+    gain: float = Field(description="The camera gain in decibels.")
+    width: int = Field(description="The camera frame width.")
+    height: int = Field(description="The camera frame height.")
+    temp: float = Field(description="The camera temperature.")
+    target_temp: float = Field(
+        description="The target temperature of the camera cooling system."
+    )
+    device_name: str = Field(description="The human readable device name.")
+    device_model_id: str = Field(description="The device model identifier.")
+    device_sn: str = Field(description="The camera serial number.")
+    bit_depth: int | str = Field(description="The bit depth of the camera sensor.")

TEM_comms/lens_correction.py

@@ -0,0 +1,10 @@
+from pigeon import BaseMessage
+from pydantic import Field
+
+
+class Transform(BaseMessage):
+    """
+    This message contains a compact representation of the generated lens correction transform.
+    """
+
+    transform: str = Field(description="The base64 encoded lens correction transform.")

TEM_comms/montage.py

@@ -1,32 +1,55 @@
 from pigeon import BaseMessage
 from typing import Mapping, Dict, Any, Optional, Tuple
 from datetime import datetime
+from pydantic import Field
 
 
 class Tile(BaseMessage):
-    raster_index: int
-    stage_position: Tuple[int, int]
-    raster_position: Tuple[int, int]
+    raster_index: int = Field(
+        description="The index of the tile incremented for each subsequent tile in the montage."
+    )
+    stage_position: Tuple[int, int] = Field(
+        description="The X-Y stage position of the tile in nanometers."
+    )
+    raster_position: Tuple[int, int] = Field(
+        description="The X-Y indicies of the tile in the montage."
+    )
 
 
 class Complete(BaseMessage):
-    montage_id: str
-    tiles: Dict[str, Tile]
-    acquisition_id: str
-    start_time: datetime
-    pixel_size: float
-    rotation_angle: float
-    aperture_centroid: Tuple[int, int]
+    """
+    This message is sent after a montage is completed.
+    """
+
+    montage_id: str = Field(description="The unique montage ID.")
+    tiles: Dict[str, Tile] = Field(
+        description="A mapping from tile IDs to tile metadata."
+    )
+    acquisition_id: str = Field(description="The corresponding TEMdb acqusition ID.")
+    start_time: datetime = Field(
+        description="The timestamp when the montage was started."
+    )
+    pixel_size: float = Field(description="The average size ofee")
+    rotation_angle: float = Field(
+        description="The necessary tile rotation in radians to line up the right-handed image coordinate system with the Stage x-y coordinate system."
+    )
+    aperture_centroid: Tuple[int, int] = Field(
+        description="The X-Y coordinates of the centroid of the imaged aperture in nanometers."
+    )
 
 
 class Minimap(BaseMessage):
-    image: Optional[str]
-    colorbar: str
-    min: Optional[float]
-    max: Optional[float]
+    image: Optional[str] = Field(description="The map as a base 64 encoded image.")
+    colorbar: str = Field(description="The colorbar as a base 64 encoded image.")
+    min: Optional[float] = Field(description="The minimum value of the colorbar.")
+    max: Optional[float] = Field(description="The maximum value of the colorbar.")
 
 
 class Minimaps(BaseMessage):
-    montage_id: str
-    montage: Minimap
-    focus: Minimap
+    """
+    This message contains multiple overview maps including a low resolution version of the montage, along with various statistics.
+    """
+
+    montage_id: str = Field(description="The unique montage ID.")
+    montage: Minimap = Field(description="The montage minimap.")
+    focus: Minimap = Field(description="The focus score map.")

TEM_comms/qc.py

@@ -1,6 +1,17 @@
 from pigeon import BaseMessage
-from typing import Literal
+from typing import Literal, Optional
+from pydantic import Field
 
 
 class Status(BaseMessage):
-    state: Literal["GOOD", "STOP_AT_END", "STOP_NOW"]
+    """
+    This message contains the overall QC status of the system.
+    """
+
+    status: Literal["GOOD", "STOP_AT_END", "STOP_NOW"] = Field(
+        description='The QC status, "GOOD" if imaging should continue, "STOP_AT_END" if imaging should be stopped at the end of the current montage, and "STOP_NOW" if imaging should be stopped immediately.'
+    )
+    reason: Optional[str] = Field(
+        default=None,
+        description="Optionally, a human readable reason for the current status.",
+    )

TEM_comms/roi.py

@@ -9,30 +9,61 @@ class Vertex(BaseMessage):
 
 
 class ROI(BaseMessage):
-    vertices: List[Vertex]
-    rotation_angle: float
-    buffer_size: float = 0.0
-    montage_id: str
-    specimen_id: Optional[str] = None
-    grid_id: Optional[str] = None
-    section_id: Optional[str] = None
-    metadata: Optional[dict] = None
+    """
+    Information about the current ROI being imaged.
+    """
+
+    vertices: List[Vertex] = Field(
+        description="A list of points defining a polygonal ROI."
+    )
+    rotation_angle: float = Field(
+        description="The rotation angle of the ROI in radians."
+    )
+    buffer_size: float = Field(
+        default=0.0,
+        description="The amount to dialate the ROI in nanometers when imaging.",
+    )
+    montage_id: str = Field(description="The montage ID to use when imaging the ROI.")
+    specimen_id: Optional[str] = Field(
+        default=None, description="The specimen ID corresponding to this ROI."
+    )
+    grid_id: Optional[str] = Field(
+        default=None, description="The grid ID where this ROI should be imaged."
+    )
+    section_id: Optional[str] = Field(
+        default=None, description="The section ID corresponding to this ROI."
+    )
+    metadata: Optional[dict] = Field(
+        default=None, description="Extra metadata about this ROI."
+    )
     queue_position: Optional[int] = Field(
         None, description="Position in queue, None means set as current"
     )
 
 
 class LoadROI(BaseMessage):
-    specimen_id: str
-    section_id: str
-    grid_id: Optional[str] = None
+    """
+    This message can be used to load an ROI from the database into the ROI queue.
+    """
+
+    specimen_id: str = Field(description="The specimen ID to load from the database.")
+    section_id: str = Field(description="The section ID to load from the database.")
+    grid_id: Optional[str] = Field(
+        default=None, description="The the grid ID where the section is loaded."
+    )
     queue_position: Optional[int] = Field(
         None, description="Position in queue, None means set as current"
     )
 
 
 class CreateROI(ROI):
-    center: Optional[Vertex] = None
+    """
+    This message can be used to create an ROI and add it to the ROI queue.
+    """
+
+    center: Optional[Vertex] = Field(
+        default=None, description="The center point of the ROI."
+    )
     tilt_angles: Optional[List[float]] = Field(
         default=[0.0],
         description="List of tilt angles in degrees for tomography series",
@@ -49,6 +80,10 @@ class CreateROI(ROI):
 
 
 class ROIStatus(BaseMessage):
+    """
+    This message contains information on the status of an individual ROI.
+    """
+
     type: str = Field(
         description="Event type: roi_added, roi_advanced, queue_cleared, queue_empty"
     )

TEM_comms/scope/__init__.py

@@ -0,0 +1,68 @@
+from pigeon import BaseMessage
+from typing import Literal, Optional, Tuple
+from pydantic import model_validator, Field
+from . import image_shift
+
+
+class Command(BaseMessage):
+    """
+    This message is used to change microscope settings.
+    """
+
+    focus: Optional[int] = Field(
+        default=None,
+        description="The desired focus value for the microscope, or None to keep the current value.",
+    )
+    mag_mode: Optional[Literal["LM", "MAG1", "MAG2"]] = Field(
+        default=None,
+        description="The desired magnification mode for the microscope, or None to keep the current value.",
+    )
+    mag: Optional[int] = Field(
+        default=None,
+        description="The desired magnification for the microscope, or None to keep the current value.",
+    )
+    brightness: Optional[int] = Field(
+        default=None,
+        description="The desired beam spread for the microscope, or None to keep the current value.",
+    )
+    beam_offset: Optional[Tuple[int, int]] = Field(
+        default=None,
+        description="The desired beam shift values, or None to keep the current value.",
+    )
+    spot_size: Optional[int] = Field(
+        default=None,
+        description="The desired spot size, or None to keep the current value.",
+    )
+    screen: Optional[Literal["up", "down"]] = Field(
+        default=None,
+        description='"up" to raise the microscope viewscreen, "down" to lower the microscope viewscreen, or None to keep the viewscreen in the current position.',
+    )
+
+    @model_validator(mode="after")
+    def check_mag(self):
+        assert (self.mag_mode is None) == (self.mag is None)
+        return self
+
+
+class Status(BaseMessage):
+    """
+    This message contains the state of the microscope.
+    """
+
+    focus: int = Field(description="The current focus value.")
+    aperture: str | None = Field(
+        description="The current status of the objective aperture, or None if unknown."
+    )
+    mag_mode: Literal["MAG", "LOWMAG"] = Field(
+        description="The curreng magnification mode."
+    )
+    mag: int = Field(description="The current magnification.")
+    tank_voltage: int = Field(
+        description="The current voltage of the tank in kilo-volts."
+    )
+    brightness: int = Field(description="The current beam spread.")
+    beam_offset: Tuple[int, int] = Field(description="The current beam shift values.")
+    spot_size: int = Field(description="The current spot size.")
+    screen: Literal["up", "down"] | None = Field(
+        description='Whether the viewscreen is currently "up", "down", or None for an unknown position.'
+    )

TEM_comms/scope/image_shift.py

@@ -0,0 +1,57 @@
+from pigeon import BaseMessage
+from typing import Optional, List, Tuple, Mapping
+from pydantic import model_validator, Field
+
+
+class Calibrate(BaseMessage):
+    """
+    This message is used to calibrate the image shifting system.
+    """
+
+    position: int = Field(description="The image shift position index to calibrate.")
+    image_shift: Tuple[int, int] = Field(
+        description="The new calibration values for this position index."
+    )
+
+
+class Status(BaseMessage):
+    """
+    This message conatins the status of the image shifting system.
+    """
+
+    enabled: bool = Field(
+        description="If the image shifting system is currently enabled."
+    )
+    current_position: int | None = Field(
+        default=None, description="The current position index, or None if disabled."
+    )
+    image_shift: Tuple[int, int] = Field(
+        description="The current image shift calibration values."
+    )
+    calibration: Mapping[int, Tuple[int, int]] = Field(
+        description="The calibration values for each position index."
+    )
+
+    @model_validator(mode="after")
+    def check_current_position(self):
+        assert self.enabled == (self.current_position is not None)
+        return self
+
+
+class Command(BaseMessage):
+    """
+    This message is used to enable and disable the image shifting system, and to switch to a predefined position.
+    """
+
+    enable: bool = Field(
+        description="Used to enable and disable the image shifting system."
+    )
+    position: Optional[int] = Field(
+        default=None,
+        description="The calibrated position index to use, or None if disabled.",
+    )
+
+    @model_validator(mode="after")
+    def check_position(self):
+        assert self.enable == (self.position is not None)
+        return self

TEM_comms/stage/aperture.py

@@ -1,17 +1,35 @@
 from pigeon import BaseMessage
-from pydantic import ConfigDict
+from pydantic import ConfigDict, Field
 
 
 class Command(BaseMessage):
+    """
+    This message is uesd to change between apertures on a substrate.
+    """
+
     model_config = ConfigDict(extra="allow")
 
-    aperture_id: int | None = None
-    calibrate: bool = False
+    aperture_id: int | None = Field(
+        default=None,
+        description="The ID of the aperture to change to, or None to remain at the current aperture.",
+    )
+    calibrate: bool = Field(
+        default=False,
+        description="Set to True to initiate aperture changing hardware calibration.",
+    )
 
 
 class Status(BaseMessage):
+    """
+    This message includes status information about the aperture changing system.
+    """
+
     model_config = ConfigDict(extra="allow")
 
-    current_aperture: int | None
-    calibrated: bool
-    error: str = ""
+    current_aperture: int | None = Field(
+        description="The ID of the current aperture, or None if unknown."
+    )
+    calibrated: bool = Field(
+        description="True if the aperture changing hardware is calibrated."
+    )
+    error: str = Field(default="", description="An optional error message.")

TEM_comms/stage/motion.py

@@ -1,22 +1,51 @@
 from typing import Optional
 from pigeon import BaseMessage
-from pydantic import ConfigDict
+from pydantic import ConfigDict, Field
 
 
 class Command(BaseMessage):
+    """
+    This message is used to specify how the stage should move the sample.
+    """
+
     model_config = ConfigDict(extra="allow")
 
-    x: int | None = None
-    y: int | None = None
-    z: Optional[int] = None
-    calibrate: bool = False
+    x: int | None = Field(
+        default=None,
+        description="The desired absolute X position of the stage in nanometers, or None to keep the current position.",
+    )
+    y: int | None = Field(
+        default=None,
+        description="The desired absolute Y position of the stage in nanometers, or None to keep the current position.",
+    )
+    z: Optional[int] = Field(
+        default=None,
+        description="The desired absolute Z position of the stage in nanometers, or None to keep the current position.",
+    )
+    calibrate: bool = Field(
+        default=False, description="Set to True to initiate stage calibration."
+    )
 
 
 class Status(BaseMessage):
+    """
+    This message includes stage motion status information.
+    """
+
     model_config = ConfigDict(extra="allow")
 
-    x: int | None
-    y: int | None
-    z: Optional[int] = None
-    in_motion: bool
-    error: str = ""
+    x: int | None = Field(
+        description="The current X position of the stage in nanometers, or None if unknown."
+    )
+    y: int | None = Field(
+        description="The current Y position of the stage in nanometers, or None if unknown."
+    )
+    z: Optional[int] = Field(
+        default=None,
+        description="The current Z position of the stage in nanometers, or None if unknown.",
+    )
+    in_motion: bool = Field(
+        description="This value is True if the stage is currently moving."
+    )
+    calibrated: bool = Field(description="True if the stage is calibrated.")
+    error: str = Field(default="", description="An optional error message.")

TEM_comms/stage/rotation.py

@@ -1,16 +1,44 @@
 from pigeon import BaseMessage
+from pydantic import Field
 
 
 class Command(BaseMessage):
-    angle_x: float | None = None
-    angle_y: float | None = None
-    eucentric_height: float | None = None
-    calibrate: bool = False
+    """
+    This message is used to rotate the sample, and to calibrate this rotation.
+    """
+
+    angle_x: float | None = Field(
+        default=None,
+        description="The desired rotation angle around the X axis in radians, or None to keep the current value.",
+    )
+    angle_y: float | None = Field(
+        default=None,
+        description="The desired rotation angle around the Y axis in radians, or None to keep the current value.",
+    )
+    eucentric_height: float | None = Field(
+        default=None,
+        description="The eucentric height of the stage in nanometers for calibration, or None to keep the current value.",
+    )
+    calibrate: bool = Field(
+        default=False, description="If True, calibrate the sample rotation hardware."
+    )
 
 
 class Status(BaseMessage):
-    angle_x: float
-    angle_y: float
-    eucentric_height: float
-    in_motion: bool
-    error: str = ""
+    """
+    This message contains the status of the sample rotation system.
+    """
+
+    angle_x: float = Field(
+        description="The current angle around the X axis in radians."
+    )
+    angle_y: float = Field(
+        description="The current angle around the Y axis in radians."
+    )
+    eucentric_height: float = Field(
+        description="The current enucentric height value in nanometers."
+    )
+    in_motion: bool = Field(
+        description="True if the rotation stage is currently moving."
+    )
+    error: str = Field(default="", description="An optional error message.")

TEM_comms/state.py

@@ -0,0 +1,23 @@
+from pigeon import BaseMessage
+from pydantic import Field
+
+
+class Current(BaseMessage):
+    """
+    This message contains the current state of the orchastration state machine.
+    """
+
+    state: str = Field(
+        description="The current state of the orchastration state machine."
+    )
+
+
+class Change(BaseMessage):
+    """
+    This message is sent on a state change of the orchastration state machine.
+    """
+
+    old: str = Field(
+        description="The previous state of the orchastration state machine."
+    )
+    new: str = Field(description="The new state of the orchastration state machine.")

TEM_comms/tile/__init__.py

@@ -1,42 +1,133 @@
-from .metadata import TileMetadata
+from .metadata import TileMetadata, ProcessingOptions
 from . import statistics
-from pydantic import BaseModel
-from typing import Literal, List
+from pydantic import BaseModel, Field
+from typing import Literal, List, Tuple, Optional
 
 
 class Preview(TileMetadata):
-    image: str
+    """
+    This message contains a downsampled tile image used for UI and calibration purposes.
+    """
+
+    image: str = Field(description="The downsampled tile as a base 64 encoded string.")
 
 
 class Mini(TileMetadata):
-    image: str
+    """
+    This message contains a highly downsampled tile image used in the creation of a minimap.
+    """
+
+    image: str = Field(description="The downsampled tile as a base 64 encoded string.")
+
 
+class Raw(TileMetadata, ProcessingOptions):
+    """
+    This message is sent whenever a new tile is stored on the filesystem and is ready for processing.
+    """
 
-class Raw(TileMetadata):
-    path: str
+    path: str = Field(
+        description="The path where the raw tile is stored.",
+        examples=["/storage/raw/69005602-15b0-4407-bf5b-4bddd6629141.tiff"],
+    )
 
 
 class Match(BaseModel):
     model_config = {"extra": "forbid"}
-    row: int
-    column: int
-    dX: float
-    dY: float
-    dXsd: float
-    dYsd: float
-    distance: float
-    rotation: float
-    match_quality: float
-    position: Literal["top", "bottom", "left", "right"]
-    pX: List[int]
-    pY: List[int]
-    qX: List[int]
-    qY: List[int]
+
+    row: int = Field(description="The row of the neighboring tile.")
+    column: int = Field(description="The column of the neighboring tile.")
+    dX: float = Field(
+        description="The X axis offset of the tile in pixels to get the tile to match."
+    )
+    dY: float = Field(
+        description="The Y axis offset of the tile in pixels to get the tile to match."
+    )
+    dXsd: float = Field(
+        description="The X axis offset standard deviation of all the feature matches."
+    )
+    dYsd: float = Field(
+        description="The Y axis offset standard deviation of all the feature matches."
+    )
+    distance: float = Field(description="The euclidian offset distance in pixels.")
+    rotation: float = Field(
+        description="The tile rotation in radians necessary to get the tiles to match."
+    )
+    position: Literal["top", "bottom", "left", "right"] = Field(
+        description="The position of matched tile relative to the captured tile."
+    )
+    pX: List[float] = Field(description="The captured tile feature X positions.")
+    pY: List[float] = Field(description="The captured tile feature Y positions.")
+    qX: List[float] = Field(description="The matched tile feature X positions.")
+    qY: List[float] = Field(description="The matched tile feature Y positions.")
 
 
 class Matches(TileMetadata):
-    matches: List[Match]
+    """
+    This message contains data relating to the matching of neighboring tiles.
+    """
+
+    matches: List[Match] = Field(
+        description="Information about how the captured tile matches to each of its available neighbors."
+    )
+
+
+class TemplateMatch(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    offset: Tuple[float, float] = Field(
+        description="The offset between the expected and actual template positions."
+    )
+    distance: float = Field(description="The distance of the offset.")
+    rotation: float = Field(description="The angle of the offset.")
+    maxVal: float = Field(
+        description="The maximum value of the template match."
+    )
+    minVal: float = Field(
+        description="The minimum value of the template match."
+    )
+    expected_offset_in_crop: Tuple[int, int] = Field(description="")
+    maxLoc: Tuple[int, int] = Field(
+        description="The maximum location of the template match."
+    )
+    matched_pos_img2: Tuple[int, int] = Field(
+        description="The template top left corner absolute location."
+    )
+    matched_center_img2: Tuple[int, int] = Field(
+        description="The template center absolute location."
+    )
+    good: bool = Field(description="True if the match is good.")
+    reject_reason: Optional[str] = Field(
+        default="", description="The reason why the match is not good."
+    )
+
+
+class TemplateMatchContainer(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    row: int = Field(description="The row of the neighboring tile.")
+    column: int = Field(description="The column of the neighboring tile.")
+    position: Literal["top", "bottom", "left", "right"] = Field(
+        description="The position of matched tile relative to the captured tile."
+    )
+    matches: List[TemplateMatch] = Field(description="A list of data structures containing the information about each individual match.")
+
+
+class TemplateMatches(TileMetadata):
+    """
+    This message contains data reltaing to template matches used for calculating the lens correction transform.
+    """
+
+    matches: List[TemplateMatchContainer] = Field(
+        description="Information about how the captured tile matches to each of its available neighbors."
+    )
 
 
 class Processed(TileMetadata):
-    path: str
+    """
+    This message contains the path to a fully processed tile stored on the filesystem.
+    """
+
+    path: str = Field(
+        description="The path where the processed tile is stored.",
+        examples=["/storage/processed/69005602-15b0-4407-bf5b-4bddd6629141.tiff"],
+    )

TEM_comms/tile/metadata.py

@@ -1,9 +1,38 @@
 from pigeon import BaseMessage
+from pydantic import Field
+from typing import Optional
 
 
 class TileMetadata(BaseMessage):
-    tile_id: str
-    montage_id: str
-    row: int
-    column: int
-    overlap: int
+    tile_id: str = Field(
+        description="The tile ID", examples=["69005602-15b0-4407-bf5b-4bddd6629141"]
+    )
+    montage_id: str = Field(
+        description="The montage ID. If a zero length string, the tile is for UI display or calibration purposes only.",
+        examples=["4330c7cf-e45b-4950-89cf-82dc0f815fe9"],
+    )
+    row: int = Field(
+        description="The row of the montage where the tile was captured.", examples=[5]
+    )
+    column: int = Field(
+        description="The column of the montage where the tile was captured.",
+        examples=[24],
+    )
+    overlap: int = Field(
+        description="The number of pixels of overlap between tiles.", examples=[512]
+    )
+
+
+class ProcessingOptions(BaseMessage):
+    brightfield: Optional[bool] = Field(
+        default=False,
+        description="If true, this tile should be used in creating the brightfield image.",
+    )
+    darkfield: Optional[bool] = Field(
+        default=False,
+        description="If true, this tile should be used in creating the darkfield image.",
+    )
+    lens_correction: Optional[bool] = Field(
+        default=False,
+        description="If true, this tile is part of a lens correction montage.",
+    )

TEM_comms/tile/statistics.py

@@ -1,17 +1,34 @@
 from .metadata import TileMetadata
 from typing import List
+from pydantic import Field
 
 
 class Focus(TileMetadata):
-    focus: float
+    """
+    This message contains the focus score, a measure of the quality of the focus of a given tile.
+    """
+
+    focus: float = Field(
+        description="The focus metric. Lower is better", ge=0, le=1, examples=[0.37]
+    )
 
 
 class Histogram(TileMetadata):
-    hist: List[int]
+    """
+    This message contains raw histogram data for a tile.
+    """
+
+    hist: List[int] = Field(description="The raw histogram data.")
 
 
 class MinMaxMean(TileMetadata):
-    min: int
-    max: int
-    mean: int
-    std: int
+    """
+    This message contains simple statistics about a processed tile.
+    """
+
+    min: int = Field(description="The minimum pixel value.", examples=[5])
+    max: int = Field(description="The maximum pixel value.", examples=[249])
+    mean: int = Field(description="The mean pixel value.", examples=[187])
+    std: int = Field(
+        description="The standard deviation of the pixel values.", examples=[25]
+    )

TEM_comms/ui.py

@@ -1,53 +1,82 @@
 from pigeon import BaseMessage
 from typing import Optional, Literal
-from pydantic import model_validator
+from pydantic import model_validator, Field
 
 
 class Edit(BaseMessage):
-    roi_id: str
-    roi_pos_x: int
-    roi_pox_y: int
-    roi_width: int
-    roi_height: int
-    roi_angle: float
+    """
+    This message is used to edit existing ROIs in the ROI queue.
+    """
+
+    roi_id: str = Field(description="The ROI id to edit.")
+    roi_pos_x: int = Field(description="The new X position of the ROI in nanometers.")
+    roi_pox_y: int = Field(description="The new Y position of the ROI in nanometers.")
+    roi_width: int = Field(description="The new width of the ROI in nanometers.")
+    roi_height: int = Field(description="The new height of the ROI in nanometers.")
+    roi_angle: float = Field(description="The new angle to rotate the ROI in radians.")
 
 
 class Run(BaseMessage):
-    session_id: Optional[str] = None
-    grid_first: Optional[int] = None
-    grid_last: Optional[int] = None
-    montage: bool = False
-    abort_now: bool = False
-    abort_at_end: bool = False
-    resume: bool = False
-    cancel: bool = False
+    """
+    This message is used start and stop automated image acquisition.
+    """
 
-    @model_validator(mode="after")
-    def check_grid(self):
-        assert self.montage != (self.grid_first is None)
-        assert self.montage != (self.grid_last is None)
-        return self
-
-    @model_validator(mode="after")
-    def check_session(self):
-        assert self.montage != (self.session_id is None)
-        return self
+    montage: bool = Field(
+        default=False,
+        description="Begin collecting montages according to the ROI queue.",
+    )
+    abort_now: bool = Field(default=False, description="Stop imaging immediately.")
+    abort_at_end: bool = Field(
+        default=False, description="Stop imaging after the current montage is complete."
+    )
+    resume: bool = Field(default=False, description="Resume from a failure state.")
+    cancel: bool = Field(
+        default=False, description="Return to preview mode from a failure state."
+    )
 
 
 class Setup(BaseMessage):
-    conch_owner: Optional[str] = None
-    auto_focus: bool = False
-    auto_exposure: bool = False
-    lens_correction: bool = False
-    acquire_brightfield: bool = False
-    acquire_darkfield: bool = False
-    center_beam: bool = False
-    spread_beam: bool = False
-    find_aperture: bool = False
-    calibrate_resolution: bool = False
-    grid: Optional[int] = None
-    mag_mode: Optional[Literal["LM", "MAG1", "MAG2"]] = None
-    mag: Optional[int] = None
+    """
+    This message is utilized to setup a microscope in a semi-automated manner. Each of the fields in this message instructs the system to run an individual setup routine.
+    """
+
+    auto_focus: bool = Field(
+        default=False, description="Automatically focus the microscope."
+    )
+    auto_exposure: bool = Field(
+        default=False, description="Optimize the camera exposure."
+    )
+    lens_correction: bool = Field(
+        default=False, description="Collect and generate a lens correction."
+    )
+    acquire_brightfield: bool = Field(
+        default=False, description="Acquire a darkfield image."
+    )
+    acquire_darkfield: bool = Field(
+        default=False, description="Acquire a brightfield image."
+    )
+    center_beam: bool = Field(
+        default=False, description="Center the beam in the image frame."
+    )
+    spread_beam: bool = Field(default=False, description="Spread the beam.")
+    find_aperture: bool = Field(
+        default=False, description="Find and move to the aperture centroid."
+    )
+    calibrate_resolution: bool = Field(
+        default=False,
+        description="Calibrate the resolution of the microscope at the current mag level.",
+    )
+    grid: Optional[int] = Field(
+        default=None, description="Change to the specified grid."
+    )
+    mag_mode: Optional[Literal["LM", "MAG1", "MAG2"]] = Field(
+        default=None,
+        description='Change to the specified mag mode. The "mag" field must also be specified.',
+    )
+    mag: Optional[int] = Field(
+        default=None,
+        description='Change to the specified magnification. "mga_mode" must also be specified.',
+    )
 
     @model_validator(mode="after")
     def check_mag(self):

{pigeon_tem_comms-1.4.1.dist-info → pigeon_tem_comms-2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pigeon-tem-comms
-Version: 1.4.1
+Version: 2.1.0
 Summary: Pigeon messages for the next generation TEM imaging system.
 Author-email: Cameron Devine <cameron.devine@alleninstitute.org>
 License: BSD 3 Clause

pigeon_tem_comms-2.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+TEM_comms/__init__.py,sha256=c2UGXOvlwg_Xy5WTQBaIS2ebmgEtJIbIwyoh7AzDjDk,1850
+TEM_comms/buffer.py,sha256=bQiYDQDOMDBEfx6QKWFKUJE14z-xn8SqwnqE1LqL5Io,546
+TEM_comms/calibration.py,sha256=Nd5u1HA5qwA_04pOeyklVLZkdV06e9y0kS2Gv9qvJNg,1383
+TEM_comms/camera.py,sha256=XrRVU-4hAGHJEbfvoj3b7359NEuTuRyqtMLL9e0V3xI,2164
+TEM_comms/lens_correction.py,sha256=KCsI1jMuPwHTxfHzx4_MP7VXdgcq6DpESQOYXV4NVqQ,290
+TEM_comms/montage.py,sha256=GevXbNdf8NGmvxR-2RPEK4JeSGtNdTXpNE_I2PSjTZ8,2157
+TEM_comms/qc.py,sha256=sFUTBjroGZrKjuL9u0LO6DT9mn10IEQsfuMv1QjgiLU,627
+TEM_comms/roi.py,sha256=dxtpPvfBGyIwGnhSI7x9F-qa8dASHV4Qt1I8DKIYNZc,3383
+TEM_comms/state.py,sha256=QGHAGtVHqbURU3qpJkuaKl8DDtuNkOqG4ubgNcQDvrg,607
+TEM_comms/ui.py,sha256=ZMRth7VKbeIlsIpZzc6vVYG3GC1ArIkxAierGNzTEDs,3185
+TEM_comms/scope/__init__.py,sha256=S33FOns1MFRD0AZ2EO-ZaDUW8cDbvpKNi_18qDS7fms,2597
+TEM_comms/scope/image_shift.py,sha256=kMx32RqUrCv2KvVYxQDqZ8LjVGJlhcu8DzmcCW11i44,1766
+TEM_comms/stage/__init__.py,sha256=UVtYKzMBI01FUADS24xSItNIjhqdZtlDeJdqsDJNVIc,67
+TEM_comms/stage/aperture.py,sha256=RoZjwmUMsgZcFTW6OYasK7g9pbz5hE0fUAOvWqVPZeA,1029
+TEM_comms/stage/motion.py,sha256=Ox_WIdhKxhkr7Q9QxbdKRKx-84az5tT_L1yUlxxNrXo,1730
+TEM_comms/stage/rotation.py,sha256=_rMk9ES7_ivMZ1AypqFVdvcuTbTQ32g9La2L1ZLdMTE,1476
+TEM_comms/tile/__init__.py,sha256=_SN7yS_rbosNsZ0n9M62WOlD_WSHnjaLoeg-vvdDeEY,4895
+TEM_comms/tile/metadata.py,sha256=iLKEmi-ocC0I_LU4YVk0AymL5zxSmmquk-fKDiKyUg0,1332
+TEM_comms/tile/statistics.py,sha256=hinAROuYdL4l0SNAdvndqetbWhDiF1ANjMoLJoPubpM,976
+pigeon_tem_comms-2.1.0.dist-info/licenses/LICENSE,sha256=tZfQIUX7uNGacTb751ZWInVenJl6OwYQihcGbYrKSts,1463
+pigeon_tem_comms-2.1.0.dist-info/METADATA,sha256=X_1JfzwWjSSCANDiSPyyNSASCEoVKIMn154Gq4aZY24,1575
+pigeon_tem_comms-2.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pigeon_tem_comms-2.1.0.dist-info/entry_points.txt,sha256=X2WfBCDgfH9XVVqiI4rLu7BLyMNuLW6WWckqXxfbrgk,38
+pigeon_tem_comms-2.1.0.dist-info/top_level.txt,sha256=3_1RcQ7xvS2dJEYnPIigo9snoKcSXSNJzPqunY0qydI,10
+pigeon_tem_comms-2.1.0.dist-info/RECORD,,

TEM_comms/scope.py

@@ -1,30 +0,0 @@
-from pigeon import BaseMessage
-from typing import Literal, Optional, Tuple
-from pydantic import model_validator
-
-
-class Command(BaseMessage):
-    focus: Optional[int] = None
-    mag_mode: Optional[Literal["LM", "MAG1", "MAG2"]] = None
-    mag: Optional[int] = None
-    brightness: Optional[int] = None
-    beam_offset: Optional[Tuple[int, int]] = None
-    spot_size: Optional[int] = None
-    screen: Optional[Literal["up", "down"]] = None
-
-    @model_validator(mode="after")
-    def check_mag(self):
-        assert (self.mag_mode is None) == (self.mag is None)
-        return self
-
-
-class Status(BaseMessage):
-    focus: int
-    aperture: str | None
-    mag_mode: Literal["MAG", "LOWMAG"]
-    mag: int
-    tank_voltage: int
-    brightness: int
-    beam_offset: Tuple[int, int]
-    spot_size: int
-    screen: Literal["up", "down"] | None

pigeon_tem_comms-1.4.1.dist-info/RECORD

@@ -1,22 +0,0 @@
-TEM_comms/__init__.py,sha256=sXY1A8yg0ihaT0Y7kSUXiNp35ibQxVJ4EjIgNoCQKOc,1504
-TEM_comms/buffer.py,sha256=Jr6fUIbUPreQSSGKWR7jkA1McyZZv3lVE8uQSER8VL4,123
-TEM_comms/calibration.py,sha256=aDxJ0VepU9A6dZR-SK1yEoTFLwzF6bz5eingSMJLcvw,327
-TEM_comms/camera.py,sha256=5tOFqm7zOPVoX6ZFr5KIMxb0jAjWpE8yo8bctvOpbcU,698
-TEM_comms/montage.py,sha256=QQ5IJcIfPb4y5QdZ-lXYNV0WLTcZUrLmOwuS0t84_2M,666
-TEM_comms/qc.py,sha256=sujy2i0wimMvrHDPEXKdaiO7xxvRcHiy83mVpATLyqA,141
-TEM_comms/roi.py,sha256=bKPBDNi1i1jxROtiw5bGh4Zn3-E0-LW_DWazYdg4PLs,2065
-TEM_comms/scope.py,sha256=7fTqhgfaNCGYsd66vCx_zTb5dW442s8cWi3RXmLNyG8,837
-TEM_comms/ui.py,sha256=pyjF9vex2qVzmKCoHdVTtDMEKRDOuhO-dWTBa2qb47Y,1484
-TEM_comms/stage/__init__.py,sha256=UVtYKzMBI01FUADS24xSItNIjhqdZtlDeJdqsDJNVIc,67
-TEM_comms/stage/aperture.py,sha256=QBO9MiVgzWJM_oAdy-9-z2qtX-pUqLyYSuMXkIDwMX4,351
-TEM_comms/stage/motion.py,sha256=EiMDAviHZo8DYjzeFcYFkbHFs90kLDsZKbrcla0y7eU,452
-TEM_comms/stage/rotation.py,sha256=tUcf6IpQ2ooRDYb51Zb4pi7pQUrBuLPiLKSg8Ebb2DY,332
-TEM_comms/tile/__init__.py,sha256=nLWbdyLdI1qkIYmnVDKt4PAu29e2VQuXqcWwWXczdgE,704
-TEM_comms/tile/metadata.py,sha256=pUxmi_C02e5nwTm51rIULkKaRz6ij5mlXylzAcDU-9c,149
-TEM_comms/tile/statistics.py,sha256=C1pMEOjwVrhjGR6R7efKJE-pR_tw9ZAGrprLIHcXc_A,245
-pigeon_tem_comms-1.4.1.dist-info/licenses/LICENSE,sha256=tZfQIUX7uNGacTb751ZWInVenJl6OwYQihcGbYrKSts,1463
-pigeon_tem_comms-1.4.1.dist-info/METADATA,sha256=5ApKdnJVbS7WxgCHjVRsgWiysPwih9-Obe3iQw9szVI,1575
-pigeon_tem_comms-1.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pigeon_tem_comms-1.4.1.dist-info/entry_points.txt,sha256=X2WfBCDgfH9XVVqiI4rLu7BLyMNuLW6WWckqXxfbrgk,38
-pigeon_tem_comms-1.4.1.dist-info/top_level.txt,sha256=3_1RcQ7xvS2dJEYnPIigo9snoKcSXSNJzPqunY0qydI,10
-pigeon_tem_comms-1.4.1.dist-info/RECORD,,