close #9 and prep release of 0.3.0

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2024-04-15
+
+### Changed
+__Locus spots visualisation__
+* QC-failed points are now...
+    * only text, no actual point
+    * sky blue rather than standard blue
+* QC-passed points are now...
+    * goldenrod/dandelion yellow rather than red
+* Color changes have been made to be more [colorblind-friendly](https://davidmathlogic.com/colorblind/).
+* Points (or text) are now visible throughout each $z$-stack, rather than just in the slice nearest the center of the Gaussian fit.
+* Each QC-pass point's position in $xy$ is shown as a stars in the $z$-slice corresponding to the truncation of the $z$-coordinate of the center of its Gaussian fit; it's shown in other slices as a circle.
+* Each QC-pass point is 50% larger in the $z$ slice corresponding to the center of its fit.
+
 ## [0.2.0] - 2024-04-14
 
 ### Added

docs/user_docs/locus-spots.md

@@ -2,7 +2,7 @@
 
 ### Quickstart
 To visualise the locus-specific spots masks, you need to __drag-and-drop files__ into an active Napari window. 
-1. First, drag one of the `PXXXX.zarr` files--from the `locus_spots_visualisation` subfolder in your analysis folder from `looptrace`--into Napari.
+1. First, drag one of the `PXXXX.zarr` files--from the `locus_spots_visualisation` (previously `locus_spot_images`) subfolder in your analysis folder from `looptrace`--into Napari.
 1. Choose to open the ZARR with the Napari native plugin(s) / readers, not this plugin's.
 1. Select "continuous" for the value of the "auto-contrast" option in the upper-left panel of the Napari window.
 1. Second, drag a the corresponding (by field of view) pair of `*qcpass.csv` and `*qcfail.csv` files into Napari.
@@ -22,4 +22,12 @@ This can makes scrolling time-consuming and will be simplified in a future relea
 
 __Finding points (centers of Gaussian fits to pixel volume)__
 
+In version 0.3 of this plugin, points should be visible throughout each z-stack, and the color of point which passed QC has been changed from red to yellow. 
+The shape is an star in the $z$ slice closest to the center of the Gaussian fit to a pixel volume, and a circle in other $z$ slices. 
+In this version, then, shape relates to $z$ position rather than to QC status; we allow point color to disambiguate QC status.
+
 In version 0.2 of this plugin, a point (blue or red indicator) can only be visible only in the z-slice closest to the z-coordinate of the the center of the Gaussian fit to a particular pixel volume. Generally, these will be more toward the middle of the z-stack rather than at either end, so focus scrolling mainly through the midrange of the z-axis.
+
+### Frequently asked questions (FAQ)
+1. Why do point centers appear _slightly_ off (thinking about subpixel resolution)?\
+    We think this comes from the fact that Napari is regarding the _center_ of the upper-left pixel as the origin, rather than the upper-left corner of the upper-left pixel.

looptrace_napari/__init__.py

@@ -1,3 +1,3 @@
 """Package-level attributes and functions"""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

looptrace_napari/_colors.py

@@ -0,0 +1,5 @@
+"""Color tools"""
+
+# See: https://davidmathlogic.com/colorblind/
+DEEP_SKY_BLUE = "#0C7BDC"
+GOLDENROD = "#FFC20A"

looptrace_napari/geometry.py

@@ -2,13 +2,12 @@
 
 from abc import abstractmethod
 from dataclasses import dataclass
-from typing import Protocol
+from typing import Protocol, Union
 
+import numpy as np
 from numpydoc_decorator import doc  # type: ignore[import-untyped]
 
-# TODO: need Python >= 3.12
-# See: https://github.com/gerlichlab/looptrace-napari/issues/6
-# from typing import override
+ZCoordinate = Union[int, float, np.float64]  # int to accommodate notion of "z-slice"
 
 
 class LocatableXY(Protocol):
@@ -23,6 +22,14 @@ def get_y_coordinate(self) -> float:
         raise NotImplementedError
 
 
+class LocatableZ(Protocol):
+    """Something that admits z-coordinate."""
+
+    @abstractmethod
+    def get_z_coordinate(self) -> ZCoordinate:
+        raise NotImplementedError
+
+
 @doc(
     summary="Bundle x and y position to create point in 2D space.",
     parameters=dict(
@@ -41,13 +48,34 @@ def __post_init__(self) -> None:
         if any(c < 0 for c in [self.x, self.y]):
             raise ValueError(f"At least one coordinate is negative! {self}")
 
-    # TODO: adopt @override once on Python >= 3.12
-    # See: https://github.com/gerlichlab/looptrace-napari/issues/6
     def get_x_coordinate(self) -> float:
         return self.x
 
-    # TODO: adopt @override once on Python >= 3.12
-    # See: https://github.com/gerlichlab/looptrace-napari/issues/6
-    # @override
     def get_y_coordinate(self) -> float:
         return self.y
+
+
+@doc(
+    summary="Bundle x and y position to create point in 2D space.",
+    parameters=dict(
+        x="Position in x",
+        y="Position in y",
+        z="Position in z",
+    ),
+    see_also=dict(
+        ImagePoint2D="Simpler, non-z implementation of an image point",
+    ),
+)
+@dataclass(kw_only=True, frozen=True)
+class ImagePoint3D(ImagePoint2D, LocatableZ):
+    z: ZCoordinate
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not isinstance(self.z, (int, float, np.float64)):
+            raise TypeError(f"Bad z ({type(self.z).__name__}: {self.z}")
+        if any(c < 0 for c in [self.x, self.y]):
+            raise ValueError(f"z-coordinate is negative! {self}")
+
+    def get_z_coordinate(self) -> ZCoordinate:
+        return self.z