pymmcore-plus 0.10.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

pymmcore_plus/__init__.py

@@ -9,7 +9,7 @@ except PackageNotFoundError:  # pragma: no cover
 
 
 from ._logger import configure_logging
-from ._util import find_micromanager
+from ._util import find_micromanager, use_micromanager
 from .core import (
     CFGCommand,
     CFGGroup,
@@ -26,6 +26,7 @@ from .core import (
     FocusDirection,
     Keyword,
     Metadata,
+    PixelFormat,
     PortType,
     PropertyType,
 )
@@ -55,6 +56,8 @@ __all__ = [
     "Keyword",
     "Metadata",
     "PCoreSignaler",
+    "PixelFormat",
     "PortType",
     "PropertyType",
+    "use_micromanager",
 ]

pymmcore_plus/_build.py

@@ -1,5 +1,7 @@
 """Clone the micro-manager source code from GitHub and build dev devices."""
 
+from __future__ import annotations
+
 import json
 import os
 import platform

pymmcore_plus/_cli.py

@@ -18,11 +18,12 @@ except ImportError:  # pragma: no cover
     ) from None
 
 import pymmcore_plus
+from pymmcore_plus._build import DEFAULT_PACKAGES, build
 from pymmcore_plus._logger import configure_logging
 from pymmcore_plus._util import USER_DATA_MM_PATH
 from pymmcore_plus.install import PLATFORM
 
-app = typer.Typer(no_args_is_help=True)
+app = typer.Typer(name="mmcore", no_args_is_help=True)
 
 
 def _show_version_and_exit(value: bool) -> None:
@@ -47,7 +48,7 @@ def _main(
 ) -> None:
     """mmcore: pymmcore-plus command line (v{version}).
 
-    For additional help on a specific command: type 'mmcore [command] --help'
+    For additional help on a specific command: type `mmcore [command] --help`
     """
     # fix for windows CI encoding and emoji printing
     if getattr(sys.stdout, "encoding", None) != "utf-8":
@@ -55,10 +56,13 @@ def _main(
             sys.stdout.reconfigure(encoding="utf-8")  # type: ignore [attr-defined]
 
 
-_main.__doc__ = typer.style(
-    (_main.__doc__ or "").format(version=pymmcore_plus.__version__),
-    fg=typer.colors.BRIGHT_YELLOW,
-)
+if "mkdocs" in sys.argv[0]:  # pragma: no cover
+    _main.__doc__ = (_main.__doc__ or "").replace(" (v{version})", "")
+else:
+    _main.__doc__ = typer.style(
+        (_main.__doc__ or "").format(version=pymmcore_plus.__version__),
+        fg=typer.colors.BRIGHT_YELLOW,
+    )
 
 
 @app.command()
@@ -91,7 +95,8 @@ def _list() -> None:
             print(f":file_folder:[bold green] {parent}")
             for item in items:
                 bullet = "   [bold yellow]*" if first else "   •"
-                print(f"{bullet} [cyan]{item}")
+                using = " [bold blue](active)" if first else ""
+                print(f"{bullet} [cyan]{item}{using}")
                 first = False
     else:
         print(":x: [bold red]There are no pymmcore-plus Micro-Manager files.")
@@ -100,7 +105,11 @@ def _list() -> None:
 
 @app.command()
 def mmstudio() -> None:  # pragma: no cover
-    """Run the Java Micro-Manager GUI."""
+    """Run the Java Micro-Manager GUI.
+
+    This command will attempt to locate an execute an ImageJ application found in
+    the active Micro-Manager directory.
+    """
     mm = pymmcore_plus.find_micromanager()
     app = (
         next((x for x in Path(mm).glob("ImageJ*") if not str(x).endswith("cfg")), None)
@@ -137,7 +146,7 @@ def install(
         show_default=False,
     ),
 ) -> None:
-    """Install Micro-Manager Device adapters."""
+    """Install Micro-Manager Device adapters from <https://download.micro-manager.org>."""
     import pymmcore_plus.install
 
     if plain_output:
@@ -286,7 +295,7 @@ def run(
 @app.command()
 def build_dev(
     devices: Optional[List[str]] = typer.Argument(
-        None, help="Device adapters to build. Defaults to DemoCamera and Utilities."
+        None, help=f"Device adapters to build. Defaults to {DEFAULT_PACKAGES}"
     ),
     dest: Path = typer.Option(
         USER_DATA_MM_PATH,
@@ -305,9 +314,10 @@ def build_dev(
         "If not specified, will prompt.",
     ),
 ) -> None:  # pragma: no cover
-    """Build DemoCamera and Utility adapters from source for apple silicon."""
-    from pymmcore_plus._build import DEFAULT_PACKAGES, build
+    """Build Micro-Manager device adapters from the git repo.
 
+    Currently only supports macos and linux.
+    """
     devices = DEFAULT_PACKAGES if not devices else devices
     try:
         build(dest, overwrite=overwrite, devices=devices)
@@ -374,6 +384,31 @@ def info() -> None:
         typer.secho(f"{key:{length}}: {value}")
 
 
+@app.command()
+def use(
+    pattern: str = typer.Argument(
+        ...,
+        help="Path to an existing directory, or pattern to match against installations "
+        "found by `mmcore list`",
+    ),
+) -> None:
+    """Change the currently used Micro-manager version/path."""
+    from pymmcore_plus._util import use_micromanager
+
+    _pth = Path(pattern)
+    if _pth.exists():
+        if not _pth.is_dir():
+            raise typer.BadParameter("must be a directory")
+        result = use_micromanager(path=_pth)
+    else:
+        try:
+            result = use_micromanager(pattern=pattern)
+        except FileNotFoundError as e:
+            raise typer.BadParameter(str(e)) from None
+
+    typer.secho(f"using {result}", fg=typer.colors.BRIGHT_GREEN)
+
+
 def _tail_file(file_path: Union[str, Path], interval: float = 0.1) -> None:
     with open(file_path) as file:
         # Move the file pointer to the end

pymmcore_plus/_util.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import datetime
 import importlib
 import os
 import platform
+import re
 import sys
 import warnings
 from collections import defaultdict
@@ -16,6 +18,7 @@ from typing import TYPE_CHECKING, cast, overload
 from platformdirs import user_data_dir
 
 if TYPE_CHECKING:
+    from re import Pattern
     from typing import Any, Callable, Iterator, Literal, TypeVar
 
     QtConnectionType = Literal["AutoConnection", "DirectConnection", "QueuedConnection"]
@@ -40,6 +43,7 @@ __all__ = ["find_micromanager", "retry", "no_stdout", "signals_backend"]
 APP_NAME = "pymmcore-plus"
 USER_DATA_DIR = Path(user_data_dir(appname=APP_NAME))
 USER_DATA_MM_PATH = USER_DATA_DIR / "mm"
+CURRENT_MM_PATH = USER_DATA_MM_PATH / ".current_mm"
 PYMMCORE_PLUS_PATH = Path(__file__).parent.parent
 
 
@@ -57,16 +61,17 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
     In order, this will look for:
 
     1. An environment variable named `MICROMANAGER_PATH`
-    2. A `Micro-Manager*` folder in the `pymmcore-plus` user data directory
+    2. A path stored in the `CURRENT_MM_PATH` file (set by `use_micromanager`).
+    3. A `Micro-Manager*` folder in the `pymmcore-plus` user data directory
        (this is the default install location when running `mmcore install`)
 
         - **Windows**: C:\Users\\[user]\AppData\Local\pymmcore-plus\pymmcore-plus
         - **macOS**: ~/Library/Application Support/pymmcore-plus
         - **Linux**: ~/.local/share/pymmcore-plus
 
-    3. A `Micro-Manager*` folder in the `pymmcore_plus` package directory (this is the
+    4. A `Micro-Manager*` folder in the `pymmcore_plus` package directory (this is the
        default install location when running `python -m pymmcore_plus.install`)
-    4. The default micro-manager install location:
+    5. The default micro-manager install location:
 
         - **Windows**: `C:/Program Files/`
         - **macOS**: `/Applications`
@@ -88,14 +93,25 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
     """
     from ._logger import logger
 
+    # we use a dict here to avoid duplicates
+    full_list: dict[str, None] = {}
+
     # environment variable takes precedence
-    full_list: list[str] = []
     env_path = os.getenv("MICROMANAGER_PATH")
     if env_path and os.path.isdir(env_path):
         if return_first:
             logger.debug("using MM path from env var: %s", env_path)
             return env_path
-        full_list.append(env_path)
+        full_list[env_path] = None
+
+    # then check for a path in CURRENT_MM_PATH
+    if CURRENT_MM_PATH.exists():
+        path = CURRENT_MM_PATH.read_text().strip()
+        if os.path.isdir(path):
+            if return_first:
+                logger.debug("using MM path from current_mm: %s", path)
+                return path
+            full_list[path] = None
 
     # then look in user_data_dir
     _folders = (p for p in USER_DATA_MM_PATH.glob("Micro-Manager*") if p.is_dir())
@@ -104,7 +120,8 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
         if return_first:
             logger.debug("using MM path from user install: %s", user_install[0])
             return str(user_install[0])
-        full_list.extend([str(x) for x in user_install])
+        for x in user_install:
+            full_list[str(x)] = None
 
     # then look for an installation in this folder (from `pymmcore_plus.install`)
     sfx = "_win" if os.name == "nt" else "_mac"
@@ -115,7 +132,8 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
         if return_first:
             logger.debug("using MM path from local install: %s", local_install[0])
             return str(local_install[0])
-        full_list.extend([str(x) for x in local_install])
+        for x in local_install:
+            full_list[str(x)] = None
 
     applications = {
         "darwin": Path("/Applications/"),
@@ -137,8 +155,59 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
         logger.debug("using MM path found in applications: %s", pth)
         return str(pth)
     if pth is not None:
-        full_list.append(str(pth))
-    return full_list
+        full_list[str(pth)] = None
+    return list(full_list)
+
+
+def _match_mm_pattern(pattern: str | Pattern[str]) -> Path | None:
+    """Locate an existing Micro-Manager folder using a regex pattern."""
+    for _path in find_micromanager(return_first=False):
+        if not isinstance(pattern, re.Pattern):
+            pattern = str(pattern)
+        if re.search(pattern, _path) is not None:
+            return Path(_path)
+    return None
+
+
+def use_micromanager(
+    path: str | Path | None = None, pattern: str | Pattern[str] | None = None
+) -> Path | None:
+    """Set the preferred Micro-Manager path.
+
+    This sets the preferred micromanager path, and persists across sessions.
+    This path takes precedence over everything *except* the `MICROMANAGER_PATH`
+    environment variable.
+
+    Parameters
+    ----------
+    path : str | Path | None
+        Path to an existing directory. This directory should contain micro-manager
+        device adapters. If `None`, the path will be determined using `pattern`.
+    pattern : str Pattern | | None
+        A regex pattern to match against the micromanager paths found by
+        `find_micromanager`. If no match is found, a `FileNotFoundError` will be raised.
+    """
+    if path is None:
+        if pattern is None:  # pragma: no cover
+            raise ValueError("One of 'path' or 'pattern' must be provided")
+        if (path := _match_mm_pattern(pattern)) is None:
+            options = "\n".join(find_micromanager(return_first=False))
+            raise FileNotFoundError(
+                f"No micromanager path found matching: {pattern!r}. Options:\n{options}"
+            )
+
+    if not isinstance(path, Path):  # pragma: no cover
+        path = Path(path)
+
+    path = path.expanduser().resolve()
+    if not path.is_dir():  # pragma: no cover
+        if not path.exists():
+            raise FileNotFoundError(f"Path not found: {path!r}")
+        raise NotADirectoryError(f"Not a directory: {path!r}")
+
+    USER_DATA_MM_PATH.mkdir(parents=True, exist_ok=True)
+    CURRENT_MM_PATH.write_text(str(path))
+    return path
 
 
 def _imported_qt_modules() -> Iterator[str]:
@@ -521,3 +590,24 @@ def system_info() -> dict[str, str]:
                     info["qt"] = f"{API_NAME} {QT_VERSION}"
 
     return info
+
+
+if sys.version_info < (3, 11):
+
+    def _utcnow() -> datetime.datetime:
+        return datetime.datetime.utcnow()
+else:
+
+    def _utcnow() -> datetime.datetime:
+        return datetime.datetime.now(datetime.UTC)
+
+
+def timestamp() -> str:
+    """Return the current timestamp, try using local timezone, in ISO format.
+
+    YYYY-MM-DD HH:MM:SS.mmmmmm+HH:MM
+    """
+    now = _utcnow()
+    with suppress(Exception):
+        now = now.astimezone()
+    return now.isoformat()

pymmcore_plus/core/__init__.py

@@ -15,6 +15,7 @@ __all__ = [
     "FocusDirection",
     "Keyword",
     "Metadata",
+    "PixelFormat",
     "PortType",
     "PropertyType",
 ]
@@ -32,6 +33,7 @@ from ._constants import (
     DeviceType,
     FocusDirection,
     Keyword,
+    PixelFormat,
     PortType,
     PropertyType,
 )

pymmcore_plus/core/_constants.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from enum import Enum, IntEnum
+from typing import Literal
 
 import pymmcore
 
@@ -163,8 +164,8 @@ class PropertyType(IntEnum):
     def to_json(self) -> str:
         return {0: "null", 1: "string", 2: "number", 3: "integer"}[self]
 
-    def __repr__(self) -> str:
-        return getattr(self.to_python(), "__name__", "None")
+    def __repr__(self) -> Literal["undefined", "float", "int", "str"]:
+        return getattr(self.to_python(), "__name__", "undefined")
 
 
 class ActionType(IntEnum):
@@ -185,13 +186,13 @@ class PortType(IntEnum):
 
 
 class FocusDirection(IntEnum):
-    FocusDirectionUnknown = pymmcore.FocusDirectionUnknown
-    FocusDirectionTowardSample = pymmcore.FocusDirectionTowardSample
-    FocusDirectionAwayFromSample = pymmcore.FocusDirectionAwayFromSample
+    Unknown = pymmcore.FocusDirectionUnknown
+    TowardSample = pymmcore.FocusDirectionTowardSample
+    AwayFromSample = pymmcore.FocusDirectionAwayFromSample
     # aliases
-    Unknown = FocusDirectionUnknown
-    TowardSample = FocusDirectionTowardSample
-    AwayFromSample = FocusDirectionAwayFromSample
+    FocusDirectionUnknown = Unknown
+    FocusDirectionTowardSample = TowardSample
+    FocusDirectionAwayFromSample = AwayFromSample
 
 
 class DeviceNotification(IntEnum):
@@ -222,6 +223,12 @@ class DeviceInitializationState(IntEnum):
 
 
 class PixelType(str, Enum):
+    """These are pixel types, as used in MMStudio and MMCoreJ wrapper.
+
+    They are only here for supporting the legacy (and probably to-be-deprecated)
+    taggedImages.
+    """
+
     UNKNOWN = ""
     GRAY8 = "GRAY8"
     GRAY16 = "GRAY16"
@@ -239,3 +246,97 @@ class PixelType(str, Enum):
                 depth, cls.UNKNOWN
             )
         return cls.GRAY32 if n_comp == 1 else cls.RGB32
+
+    def to_pixel_format(self) -> PixelFormat:
+        return {
+            self.GRAY8: PixelFormat.MONO8,
+            self.GRAY16: PixelFormat.MONO16,
+            self.GRAY32: PixelFormat.MONO32,
+            self.RGB32: PixelFormat.RGB8,
+            self.RGB64: PixelFormat.RGB16,
+        }[self]
+
+
+class PixelFormat(str, Enum):
+    """Subset of GeniCam Pixel Format names used by pymmcore-plus.
+
+    (This is similar to PixelType, but follows GeniCam standards.)
+
+    See <https://docs.baslerweb.com/pixel-format#unpacked-and-packed-pixel-formats>
+    for helpful clarifications.  Note that **unpacked** pixel formats (like
+    Mono8, Mono12, Mono16) are always 8-bit aligned. Meaning Mono12 is actually
+    a 16-bit buffer.
+
+    Attributes
+    ----------
+    MONO8 : str
+        8-bit (unpacked) monochrome pixel format.
+    MONO10 : str
+        10-bit (unpacked) monochrome pixel format. (16-bit buffer)
+    MONO12 : str
+        12-bit (unpacked) monochrome pixel format. (16-bit buffer)
+    MONO14 : str
+        14-bit (unpacked) monochrome pixel format. (16-bit buffer)
+    MONO16 : str
+        16-bit (unpacked) monochrome pixel format
+    MONO32 : str
+        32-bit (unpacked) monochrome pixel format
+    RGB8 : str
+        8-bit RGB pixel format. (24-bit buffer)
+    RGB10 : str
+        10-bit RGB pixel format. (48-bit buffer)
+    RGB12 : str
+        12-bit RGB pixel format. (48-bit buffer)
+    RGB14 : str
+        14-bit RGB pixel format. (48-bit buffer)
+    RGB16 : str
+        16-bit RGB pixel format. (48-bit buffer)
+    """
+
+    MONO8 = "Mono8"
+    MONO10 = "Mono10"
+    MONO12 = "Mono12"
+    MONO14 = "Mono14"
+    MONO16 = "Mono16"
+    MONO32 = "Mono32"
+    RGB8 = "RGB8"
+    RGB10 = "RGB10"
+    RGB12 = "RGB12"
+    RGB14 = "RGB14"
+    RGB16 = "RGB16"
+
+    @classmethod
+    def pick(cls, bit_depth: int, n_comp: int = 1) -> PixelFormat:
+        try:
+            return PIXEL_FORMATS[n_comp][bit_depth]
+        except KeyError as e:
+            raise NotImplementedError(
+                f"Unsupported Pixel Format {bit_depth=} {n_comp=}"
+            ) from e
+
+    @classmethod
+    def for_current_camera(cls, core: pymmcore.CMMCore) -> PixelFormat:
+        n_comp = core.getNumberOfComponents()
+        if n_comp == 4:
+            n_comp = 3
+        return cls.pick(core.getImageBitDepth(), n_comp)
+
+
+# map of {number of components: {bit depth: PixelFormat}}
+PIXEL_FORMATS: dict[int, dict[int, PixelFormat]] = {
+    1: {
+        8: PixelFormat.MONO8,
+        10: PixelFormat.MONO10,
+        12: PixelFormat.MONO12,
+        14: PixelFormat.MONO14,
+        16: PixelFormat.MONO16,
+        32: PixelFormat.MONO32,
+    },
+    3: {
+        8: PixelFormat.RGB8,
+        10: PixelFormat.RGB10,
+        12: PixelFormat.RGB12,
+        14: PixelFormat.RGB14,
+        16: PixelFormat.RGB16,
+    },
+}