pymmcore-plus 0.9.3__py3-none-any.whl → 0.13.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,
 )
@@ -33,7 +34,6 @@ from .core.events import CMMCoreSignaler, PCoreSignaler
 from .mda._runner import GeneratorMDASequence
 
 __all__ = [
-    "__version__",
     "ActionType",
     "CFGCommand",
     "CFGGroup",
@@ -41,7 +41,6 @@ __all__ = [
     "CMMCoreSignaler",
     "ConfigGroup",
     "Configuration",
-    "configure_logging",
     "Device",
     "DeviceAdapter",
     "DeviceDetectionStatus",
@@ -49,12 +48,16 @@ __all__ = [
     "DeviceNotification",
     "DeviceProperty",
     "DeviceType",
-    "find_micromanager",
     "FocusDirection",
     "GeneratorMDASequence",
     "Keyword",
     "Metadata",
     "PCoreSignaler",
+    "PixelFormat",
     "PortType",
     "PropertyType",
+    "__version__",
+    "configure_logging",
+    "find_micromanager",
+    "use_micromanager",
 ]

pymmcore_plus/_benchmark.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import timeit
+import warnings
+from typing import TYPE_CHECKING
+
+from pymmcore_plus import CMMCorePlus, DeviceType
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator, Sequence
+
+    from pymmcore_plus.core._device import Device
+
+
+class Benchmark:
+    device_type = DeviceType.Camera
+
+    def __init__(self, core: CMMCorePlus, label: str = "") -> None:
+        self.core = core
+        self.label = label
+
+    def setup(self) -> None:
+        pass
+
+    def device(self) -> Device | None:
+        if self.label is not None:
+            return self.core.getDeviceObject(self.label)
+        return None
+
+    def run(self, number: int) -> Iterator[tuple[str, float | str]]:
+        # get methods in the order of definition, in reverse MRO order
+
+        try:
+            self.setup()
+        except Exception as e:  # pragma: no cover
+            warnings.warn(
+                f"Setup failed on device {self.label!r}: {e}",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return
+
+        methods: list[str] = []
+        for base in reversed(type(self).mro()):
+            methods.extend(m for m in base.__dict__ if m.startswith("bench_"))
+
+        for method_name in methods:
+            try:
+                t = timeit.timeit(getattr(self, method_name), number=number)
+                result: float | str = round(1000 * t / number, 3)
+            except Exception as e:
+                result = str(e)
+            yield method_name[6:], result
+
+
+class CoreBenchmark(Benchmark):
+    device_type = DeviceType.Core
+
+    def bench_getDeviceAdapterNames(self) -> None:
+        self.core.getDeviceAdapterNames()
+
+    def bench_getLoadedDevices(self) -> None:
+        self.core.getLoadedDevices()
+
+    def bench_getSystemState(self) -> None:
+        self.core.getSystemState()
+
+
+class CameraBenchmark(Benchmark):
+    device_type = DeviceType.Camera
+
+    def setup(self) -> None:
+        self.core.setCameraDevice(self.label)
+        self.core.setExposure(self.label, 1)
+
+    def bench_getMultiROI(self) -> None:
+        self.core.getMultiROI()
+
+    def bench_getExposure(self) -> None:
+        self.core.getExposure(self.label)
+
+    def bench_snapImage(self) -> None:
+        self.core.snapImage()
+
+    def bench_getImage(self) -> None:
+        self.core.getImage()
+
+    def bench_getImageWidth(self) -> None:
+        self.core.getImageWidth()
+
+    def bench_getImageHeight(self) -> None:
+        self.core.getImageHeight()
+
+    def bench_getImageBufferSize(self) -> None:
+        self.core.getImageBufferSize()
+
+    def bench_getImageBitDepth(self) -> None:
+        self.core.getImageBitDepth()
+
+    def bench_getNumberOfComponents(self) -> None:
+        self.core.getNumberOfComponents()
+
+    def bench_getNumberOfCameraChannels(self) -> None:
+        self.core.getNumberOfCameraChannels()
+
+
+class XYStageBenchmark(Benchmark):
+    device_type = DeviceType.XYStage
+
+    def setup(self) -> None:
+        self.core.setXYStageDevice(self.label)
+        self.position = self.core.getXYPosition(self.label)
+
+    def bench_getXYPosition(self) -> None:
+        self.core.getXYPosition(self.label)
+
+    def bench_getXPosition(self) -> None:
+        self.core.getXPosition(self.label)
+
+    def bench_getYPosition(self) -> None:
+        self.core.getYPosition(self.label)
+
+    def bench_setXYPosition(self) -> None:
+        self.core.setXYPosition(self.label, *self.position)
+
+    def bench_setRelativeXYPosition(self) -> None:
+        self.core.setRelativeXYPosition(self.label, 0, 0)
+
+    def bench_isXYStageSequenceable(self) -> None:
+        self.core.isXYStageSequenceable(self.label)
+
+
+class StageBenchmark(Benchmark):
+    device_type = DeviceType.Stage
+
+    def setup(self) -> None:
+        self.position = self.core.getPosition(self.label)
+
+    def bench_getPosition(self) -> None:
+        self.core.getPosition(self.label)
+
+    def bench_setPosition(self) -> None:
+        self.core.setPosition(self.label, self.position)
+
+    def bench_setRelativePosition(self) -> None:
+        self.core.setRelativePosition(self.label, 0)
+
+    def bench_isStageSequenceable(self) -> None:
+        self.core.isStageSequenceable(self.label)
+
+    def bench_isStageLinearSequenceable(self) -> None:
+        self.core.isStageLinearSequenceable(self.label)
+
+
+class StateBenchmark(Benchmark):
+    device_type = DeviceType.State
+
+    def setup(self) -> None:
+        self.initial_state = self.core.getState(self.label)
+        try:
+            self.labels: Sequence[str] = self.core.getStateLabels(self.label)
+        except Exception:
+            self.labels = []
+
+    def bench_getState(self) -> None:
+        self.core.getState(self.label)
+
+    def bench_setState(self) -> None:
+        self.core.setState(self.label, self.initial_state)
+
+    def bench_getNumberOfStates(self) -> None:
+        self.core.getNumberOfStates(self.label)
+
+    def bench_getStateLabel(self) -> None:
+        self.core.getStateLabel(self.label)
+
+    def bench_getStateFromLabel(self) -> None:
+        for label in self.labels:
+            self.core.getStateFromLabel(self.label, label)
+
+
+def benchmark_core_and_devices(
+    core: CMMCorePlus, number: int = 100
+) -> Iterable[Device | None | tuple[str, float | str]]:
+    """Take an initialized core with devices and benchmark various methods.
+
+    Yields
+    ------
+    Device | None | tuple[str, float | str]
+        If a `Device`, it is the device object being benchmarked.
+        If None, it is the core object being benchmarked.
+        If a tuple, it is the method name and the time taken to run it.
+    """
+    for cls in Benchmark.__subclasses__():
+        if cls.device_type == DeviceType.Core:
+            bench = cls(core, "Core")
+            yield bench.device()
+            yield from bench.run(number)
+        else:
+            for dev in core.getLoadedDevicesOfType(cls.device_type):
+                bench = cls(core, dev)
+                yield bench.device()
+                yield from bench.run(number)

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
@@ -9,12 +11,15 @@ import subprocess
 import tempfile
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Iterator, Sequence
+from typing import TYPE_CHECKING
 from urllib.request import Request, urlopen
 
 from rich import print
 from rich.prompt import Prompt
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
 MM_REPO = "micro-manager/micro-manager"
 MMCORE_AND_DEV = "micro-manager/mmCoreAndDevices"
 MM_REPO_URL = f"https://github.com/{MM_REPO}.git"

pymmcore_plus/_cli.py

@@ -6,7 +6,10 @@ import sys
 import time
 from contextlib import suppress
 from pathlib import Path
-from typing import List, Optional, Union, cast
+from typing import Optional, Union, cast
+
+from pymmcore_plus.core._device import Device
+from pymmcore_plus.core._mmcore_plus import CMMCorePlus
 
 try:
     import typer
@@ -18,23 +21,41 @@ 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:
     if value:
-        import pymmcore
-
         typer.echo(f"pymmcore-plus v{pymmcore_plus.__version__}")
-        typer.echo(f"pymmcore v{pymmcore.__version__}")  # type: ignore [attr-defined]
-        typer.echo(f"MMCore v{pymmcore.CMMCore().getAPIVersionInfo()}")
+        try:
+            import pymmcore_nano as pymmcore
+
+            typer.echo(f"pymmcore-nano v{pymmcore.__version__}")
+        except ImportError:
+            import pymmcore
+
+            typer.echo(f"pymmcore v{pymmcore.__version__}")
+        typer.echo(f"MMCore v{pymmcore.CMMCore().getVersionInfo()}")
+        typer.echo(f"{pymmcore.CMMCore().getAPIVersionInfo()}")
         raise typer.Exit()
 
 
+CONFIG_PARAM = typer.Option(
+    None,
+    "-c",
+    "--config",
+    dir_okay=False,
+    exists=True,
+    resolve_path=True,
+    help="Path to Micro-Manager system configuration file.",
+)
+
+
 @app.callback()
 def _main(
     version: Optional[bool] = typer.Option(
@@ -47,18 +68,21 @@ 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":
         with suppress(AttributeError):
-            sys.stdout.reconfigure(encoding="utf-8")  # type: ignore [attr-defined]
+            sys.stdout.reconfigure(encoding="utf-8")  # type: ignore [union-attr]
 
 
-_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 +115,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 +125,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 +166,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:
@@ -159,15 +188,7 @@ def run(
         resolve_path=True,
         help="Path to useq-schema file.",
     ),
-    config: Optional[Path] = typer.Option(
-        None,
-        "-c",
-        "--config",
-        dir_okay=False,
-        exists=True,
-        resolve_path=True,
-        help="Path to Micro-Manager system configuration file.",
-    ),
+    config: Optional[Path] = CONFIG_PARAM,
     z_go_up: Optional[bool] = typer.Option(None, help="Acquire from bottom to top."),
     z_top: Optional[float] = typer.Option(None, help="Top of z-stack."),
     z_bottom: Optional[float] = typer.Option(None, help="Bottom of z-stack."),
@@ -181,10 +202,10 @@ def run(
         None, help="Asymmetric range of z-stack below position."
     ),
     z_step: Optional[float] = typer.Option(None, help="Step size of z-stack."),
-    z_relative: Optional[List[float]] = typer.Option(
+    z_relative: Optional[list[float]] = typer.Option(
         None, "-zr", help="Relative z-positions to acquire (may use multiple times)."
     ),
-    z_absolute: Optional[List[float]] = typer.Option(
+    z_absolute: Optional[list[float]] = typer.Option(
         None, "-za", help="Absolute z-positions to acquire (may use multiple times)."
     ),
     t_interval: Optional[float] = typer.Option(
@@ -198,7 +219,7 @@ def run(
     axis_order: Optional[str] = typer.Option(
         None, help="Order of axes to acquire (e.g. 'TPCZ')."
     ),
-    channel: Optional[List[str]] = typer.Option(
+    channel: Optional[list[str]] = typer.Option(
         None,
         help="\bChannel to acquire. Argument is a string of the following form:\n"
         '\b - name: "DAPI"\n'
@@ -285,8 +306,8 @@ def run(
 
 @app.command()
 def build_dev(
-    devices: Optional[List[str]] = typer.Argument(
-        None, help="Device adapters to build. Defaults to DemoCamera and Utilities."
+    devices: Optional[list[str]] = typer.Argument(
+        None, help=f"Device adapters to build. Defaults to {DEFAULT_PACKAGES}"
     ),
     dest: Path = typer.Option(
         USER_DATA_MM_PATH,
@@ -305,9 +326,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 +396,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
@@ -388,5 +435,58 @@ def _tail_file(file_path: Union[str, Path], interval: float = 0.1) -> None:
             time.sleep(1)
 
 
+@app.command()
+def bench(
+    config: Optional[Path] = CONFIG_PARAM,
+    number: int = typer.Option(
+        10, "-n", "--number", help="Number of iterations for each test."
+    ),
+) -> None:
+    """Run a benchmark of Core and Devices loaded with `config` (or Demo)."""
+    from rich.console import Console
+    from rich.live import Live
+    from rich.table import Table
+
+    from pymmcore_plus._benchmark import benchmark_core_and_devices
+
+    console = Console()
+
+    core = CMMCorePlus()
+    if config is not None:
+        console.log(
+            f"Loading config {config} ...",
+            style="bright_blue",
+            end="",
+        )
+        core.loadSystemConfiguration(str(config))
+    else:
+        console.log("Loading DEMO configuration ...", style="bright_blue", end="")
+        core.loadSystemConfiguration()
+    console.log("Loaded.", style="bright_blue")
+
+    table = Table()
+    table.add_column("Method")
+    table.add_column("Time (ms)")
+
+    with Live(table, console=console, refresh_per_second=4):
+        for item in benchmark_core_and_devices(core, number):
+            if item is None:
+                table.add_row("Device: Core", "------", style="yellow")
+            elif isinstance(item, Device):
+                console.print(
+                    f"Measuring ({item.type()}) Device: "
+                    f"{item.label!r} <{item.library()}::{item.name()}>"
+                    f": {item.description()}",
+                    style="#333333",
+                )
+                table.add_row(f"Device: {item.label}", "------", style="yellow")
+            else:
+                method, time = item
+                if isinstance(time, float):
+                    table.add_row(method, f"{time:.4f}")
+                else:
+                    table.add_row(method, str(time), style="red")
+
+
 def main() -> None:  # pragma: no cover
     app()

pymmcore_plus/_logger.py

@@ -6,22 +6,23 @@ import sys
 from contextlib import contextmanager
 from logging.handlers import RotatingFileHandler
 from pathlib import Path
-from typing import ClassVar, Iterator
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
 
 __all__ = ["logger"]
 
 
 logger = logging.getLogger("pymmcore-plus")
 
-
+PYMM_LOG_FILE = os.getenv("PYMM_LOG_FILE", "")
 DEFAULT_LOG_LEVEL: str = os.getenv("PYMM_LOG_LEVEL", "INFO").upper()
-if any(x.endswith("pytest") for x in sys.argv):
+
+if "PYTEST_RUNNING" in os.environ:
     LOG_FILE = None
-elif "PYMM_LOG_FILE" in os.environ:
-    if os.environ["PYMM_LOG_FILE"].lower() in ("", "0", "false", "no", "none"):
-        LOG_FILE = None
-    else:
-        LOG_FILE = Path(os.environ["PYMM_LOG_FILE"]).expanduser().resolve()
+elif PYMM_LOG_FILE not in ("", "0", "false", "no", "none"):
+    LOG_FILE = Path(PYMM_LOG_FILE).expanduser().resolve()
 else:
     from ._util import USER_DATA_DIR
 
@@ -117,9 +118,17 @@ def configure_logging(
 
     # automatically log to stderr
     if log_to_stderr and sys.stderr:
-        stderr_handler = logging.StreamHandler(sys.stderr)
+        # try to use rich for stderr logging
+        # fallback to plain text if rich is not installed
+        try:
+            from rich.logging import RichHandler
+
+            stderr_handler: logging.Handler = RichHandler()
+        except ImportError:
+            stderr_handler = logging.StreamHandler(sys.stderr)
+            stderr_handler.setFormatter(CustomFormatter())
+
         stderr_handler.setLevel(stderr_level)
-        stderr_handler.setFormatter(CustomFormatter())
         logger.addHandler(stderr_handler)
 
     # automatically log to file

pymmcore_plus/_pymmcore.py

@@ -0,0 +1,12 @@
+"""Internal module to choose between pymmcore and pymmcore-nano."""
+
+try:
+    from pymmcore_nano import *  # noqa F403
+    from pymmcore_nano import __version__
+
+    BACKEND = "pymmcore-nano"
+except ImportError:
+    from pymmcore import *  # noqa F403
+    from pymmcore import __version__  # noqa F401
+
+    BACKEND = "pymmcore"