# pymmcore-plus
[](https://github.com/pymmcore-plus/pymmcore-plus/raw/master/LICENSE)
[](https://pypi.org/project/pymmcore-plus)
[](https://pypi.org/project/pymmcore-plus)
[](https://anaconda.org/conda-forge/pymmcore-plus)
[](https://github.com/pymmcore-plus/pymmcore-plus/actions/workflows/ci.yml)
[](https://pymmcore-plus.github.io/pymmcore-plus/)
[](https://codecov.io/gh/pymmcore-plus/pymmcore-plus)
[](https://codspeed.io/pymmcore-plus/pymmcore-plus)
`pymmcore-plus` extends [pymmcore](https://github.com/micro-manager/pymmcore)
(python bindings for the C++ [micro-manager
core](https://github.com/micro-manager/mmCoreAndDevices/)) with a number of
features designed to facilitate working with **Micro-manager in pure python/C
environments**.
- `pymmcore_plus.CMMCorePlus` is a drop-in replacement subclass of
`pymmcore.CMMCore` that provides a number of helpful overrides and additional
convenience functions beyond the standard [CMMCore
API](https://javadoc.scijava.org/Micro-Manager-Core/mmcorej/CMMCore.html). See
[CMMCorePlus
documentation](https://pymmcore-plus.github.io/pymmcore-plus/api/cmmcoreplus/)
for details.
- `pymmcore-plus` includes an [acquisition engine](https://pymmcore-plus.github.io/pymmcore-plus/guides/mda_engine/)
that drives micro-manager for conventional multi-dimensional experiments. It accepts an
[MDASequence](https://pymmcore-plus.github.io/useq-schema/schema/sequence/)
from [useq-schema](https://pymmcore-plus.github.io/useq-schema/) for
experiment design/declaration.
- Adds a [callback
system](https://pymmcore-plus.github.io/pymmcore-plus/api/events/) that adapts
the CMMCore callback object to an existing python event loop (such as Qt, or
perhaps asyncio/etc...). The `CMMCorePlus` class also fixes a number of
"missed" events that are not currently emitted by the CMMCore API.
## Documentation
https://pymmcore-plus.github.io/pymmcore-plus/
## Why not just use `pymmcore` directly?
[pymmcore](https://github.com/micro-manager/pymmcore) is (and should probably
remain) a thin SWIG wrapper for the C++ code at the core of the
[Micro-Manager](https://github.com/micro-manager/mmCoreAndDevices/) project. It
is sufficient to control micromanager via python, but lacks some "niceties" that
python users are accustomed to. This library:
- extends the `pymmcore.CMMCore` object with [additional
methods](https://pymmcore-plus.github.io/pymmcore-plus/api/cmmcoreplus/)
- fixes emission of a number of events in `MMCore`.
- provide proper python interfaces for various objects like
[`Configuration`](https://pymmcore-plus.github.io/pymmcore-plus/api/configuration/)
and [`Metadata`](https://pymmcore-plus.github.io/pymmcore-plus/api/metadata/).
- provides an [object-oriented
API](https://pymmcore-plus.github.io/pymmcore-plus/api/device/) for Devices
and their properties.
- uses more interpretable `Enums` rather than `int` for [various
constants](https://pymmcore-plus.github.io/pymmcore-plus/api/constants/)
- improves docstrings and type annotations.
- generally feel more pythonic (note however, `camelCase` method names from the
CMMCore API are _not_ substituted with `snake_case`).
## How does this relate to `Pycro-Manager`?
[Pycro-Manager](https://github.com/micro-manager/pycro-manager) is an impressive
library written by Henry Pinkard designed to make it easier to work with and
control the Java Micro-manager application using python. As such, it requires
Java to be installed and running in the background (either via the micro-manager
GUI application directly, or via a headless process). The python half
communicates with the Java half using ZeroMQ messaging.
**In brief**: while `Pycro-Manager` provides a python API to control the Java
Micro-manager application (which in turn controls the C++ core), `pymmcore-plus`
provides a python API to control the C++ core directly, without the need for
Java in the loop. Each has its own advantages and disadvantages! With
pycro-manager you immediately get the entire existing micro-manager ecosystem
and GUI application. With pymmcore-plus you don't need to install Java, and you
have direct access to the memory buffers used by the C++ core.
## Quickstart
### Install
from pip
```sh
pip install pymmcore-plus
# or, add the [cli] extra if you wish to use the `mmcore` command line tool:
pip install "pymmcore-plus[cli]"
# add the [io] extra if you wish to use the tiff or zarr writers
pip install "pymmcore-plus[io]"
```
from conda
```sh
conda install -c conda-forge pymmcore-plus
```
dev version from github
```sh
pip install 'pymmcore-plus[cli] @ git+https://github.com/pymmcore-plus/pymmcore-plus'
```
Usually, you'll then want to install the device adapters. Assuming you've
installed with `pip install "pymmcore-plus[cli]"`, you can run:
```sh
mmcore install
```
(you can also download these manually from [micro-manager.org](https://micro-manager.org/Micro-Manager_Nightly_Builds))
_See [installation documentation ](https://pymmcore-plus.github.io/pymmcore-plus/install/) for more details._
### Usage
Then use the core object as you would `pymmcore.CMMCore`...
but with [more features](https://pymmcore-plus.github.io/pymmcore-plus/api/cmmcoreplus/) :smile:
```python
from pymmcore_plus import CMMCorePlus
core = CMMCorePlus()
...
```
### Examples
See a number of [usage examples in the
documentation](http://pymmcore-plus.github.io/pymmcore-plus/examples/mda/).
You can find some basic python scripts in the [examples](examples) directory of
this repository
## Contributing
Contributions are welcome! See [contributing guide](http://pymmcore-plus.github.io/pymmcore-plus/contributing/).
Raw data
{
"_id": null,
"home_page": null,
"name": "pymmcore-plus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "micro-manager, microscope, smart-microscopy",
"author": null,
"author_email": "Talley Lambert <talley.lambert@gmail.com>, Federico Gasparoli <federico.gasparoli@gmail.com>, Ian Hunt-Isaak <ianhuntisaak@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d6/40/50023cff76ee31860b361f2bf49095096e3b5776ec192a70d37be8694aba/pymmcore_plus-0.12.0.tar.gz",
"platform": null,
"description": "# pymmcore-plus\n\n[](https://github.com/pymmcore-plus/pymmcore-plus/raw/master/LICENSE)\n[](https://pypi.org/project/pymmcore-plus)\n[](https://pypi.org/project/pymmcore-plus)\n[](https://anaconda.org/conda-forge/pymmcore-plus)\n[](https://github.com/pymmcore-plus/pymmcore-plus/actions/workflows/ci.yml)\n[](https://pymmcore-plus.github.io/pymmcore-plus/)\n[](https://codecov.io/gh/pymmcore-plus/pymmcore-plus)\n[](https://codspeed.io/pymmcore-plus/pymmcore-plus)\n\n`pymmcore-plus` extends [pymmcore](https://github.com/micro-manager/pymmcore)\n(python bindings for the C++ [micro-manager\ncore](https://github.com/micro-manager/mmCoreAndDevices/)) with a number of\nfeatures designed to facilitate working with **Micro-manager in pure python/C\nenvironments**.\n\n- `pymmcore_plus.CMMCorePlus` is a drop-in replacement subclass of\n `pymmcore.CMMCore` that provides a number of helpful overrides and additional\n convenience functions beyond the standard [CMMCore\n API](https://javadoc.scijava.org/Micro-Manager-Core/mmcorej/CMMCore.html). See\n [CMMCorePlus\n documentation](https://pymmcore-plus.github.io/pymmcore-plus/api/cmmcoreplus/)\n for details.\n- `pymmcore-plus` includes an [acquisition engine](https://pymmcore-plus.github.io/pymmcore-plus/guides/mda_engine/) \n that drives micro-manager for conventional multi-dimensional experiments. It accepts an\n [MDASequence](https://pymmcore-plus.github.io/useq-schema/schema/sequence/)\n from [useq-schema](https://pymmcore-plus.github.io/useq-schema/) for\n experiment design/declaration.\n- Adds a [callback\n system](https://pymmcore-plus.github.io/pymmcore-plus/api/events/) that adapts\n the CMMCore callback object to an existing python event loop (such as Qt, or\n perhaps asyncio/etc...). The `CMMCorePlus` class also fixes a number of\n \"missed\" events that are not currently emitted by the CMMCore API.\n\n## Documentation\n\nhttps://pymmcore-plus.github.io/pymmcore-plus/\n\n## Why not just use `pymmcore` directly?\n\n[pymmcore](https://github.com/micro-manager/pymmcore) is (and should probably\nremain) a thin SWIG wrapper for the C++ code at the core of the\n[Micro-Manager](https://github.com/micro-manager/mmCoreAndDevices/) project. It\nis sufficient to control micromanager via python, but lacks some \"niceties\" that\npython users are accustomed to. This library:\n\n- extends the `pymmcore.CMMCore` object with [additional\n methods](https://pymmcore-plus.github.io/pymmcore-plus/api/cmmcoreplus/)\n- fixes emission of a number of events in `MMCore`.\n- provide proper python interfaces for various objects like\n [`Configuration`](https://pymmcore-plus.github.io/pymmcore-plus/api/configuration/)\n and [`Metadata`](https://pymmcore-plus.github.io/pymmcore-plus/api/metadata/).\n- provides an [object-oriented\n API](https://pymmcore-plus.github.io/pymmcore-plus/api/device/) for Devices\n and their properties.\n- uses more interpretable `Enums` rather than `int` for [various\n constants](https://pymmcore-plus.github.io/pymmcore-plus/api/constants/)\n- improves docstrings and type annotations.\n- generally feel more pythonic (note however, `camelCase` method names from the\n CMMCore API are _not_ substituted with `snake_case`).\n\n## How does this relate to `Pycro-Manager`?\n\n[Pycro-Manager](https://github.com/micro-manager/pycro-manager) is an impressive\nlibrary written by Henry Pinkard designed to make it easier to work with and\ncontrol the Java Micro-manager application using python. As such, it requires\nJava to be installed and running in the background (either via the micro-manager\nGUI application directly, or via a headless process). The python half\ncommunicates with the Java half using ZeroMQ messaging.\n\n**In brief**: while `Pycro-Manager` provides a python API to control the Java\nMicro-manager application (which in turn controls the C++ core), `pymmcore-plus`\nprovides a python API to control the C++ core directly, without the need for\nJava in the loop. Each has its own advantages and disadvantages! With\npycro-manager you immediately get the entire existing micro-manager ecosystem\nand GUI application. With pymmcore-plus you don't need to install Java, and you\nhave direct access to the memory buffers used by the C++ core.\n\n## Quickstart\n\n### Install\n\nfrom pip\n\n```sh\npip install pymmcore-plus\n\n# or, add the [cli] extra if you wish to use the `mmcore` command line tool:\npip install \"pymmcore-plus[cli]\"\n\n# add the [io] extra if you wish to use the tiff or zarr writers\npip install \"pymmcore-plus[io]\"\n```\n\nfrom conda\n\n```sh\nconda install -c conda-forge pymmcore-plus\n```\n\ndev version from github\n\n```sh\npip install 'pymmcore-plus[cli] @ git+https://github.com/pymmcore-plus/pymmcore-plus'\n```\n\nUsually, you'll then want to install the device adapters. Assuming you've\ninstalled with `pip install \"pymmcore-plus[cli]\"`, you can run:\n\n```sh\nmmcore install\n```\n\n(you can also download these manually from [micro-manager.org](https://micro-manager.org/Micro-Manager_Nightly_Builds))\n\n_See [installation documentation ](https://pymmcore-plus.github.io/pymmcore-plus/install/) for more details._\n\n### Usage\n\nThen use the core object as you would `pymmcore.CMMCore`...\nbut with [more features](https://pymmcore-plus.github.io/pymmcore-plus/api/cmmcoreplus/) :smile:\n\n```python\nfrom pymmcore_plus import CMMCorePlus\n\ncore = CMMCorePlus()\n...\n```\n\n### Examples\n\nSee a number of [usage examples in the\ndocumentation](http://pymmcore-plus.github.io/pymmcore-plus/examples/mda/).\n\nYou can find some basic python scripts in the [examples](examples) directory of\nthis repository\n\n## Contributing\n\nContributions are welcome! See [contributing guide](http://pymmcore-plus.github.io/pymmcore-plus/contributing/).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "pymmcore superset providing improved APIs, event handling, and a pure python acquisition engine",
"version": "0.12.0",
"project_urls": {
"Documentation": "https://pymmcore-plus.github.io/pymmcore-plus",
"Source": "https://github.com/pymmcore-plus/pymmcore-plus",
"Tracker": "https://github.com/pymmcore-plus/pymmcore-plus/issues"
},
"split_keywords": [
"micro-manager",
" microscope",
" smart-microscopy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f288c3a94f65b527aa4631426bed957add0e4e0bcc531a9686ff1cb73fc5efab",
"md5": "b7ef82a76b0b475c16903076d48fa62c",
"sha256": "17230f98aba055446c7927f53d58156edfa5e9f5b2d23c9c2b52f8e04a7d24d9"
},
"downloads": -1,
"filename": "pymmcore_plus-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7ef82a76b0b475c16903076d48fa62c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 142730,
"upload_time": "2024-10-05T15:26:48",
"upload_time_iso_8601": "2024-10-05T15:26:48.002789Z",
"url": "https://files.pythonhosted.org/packages/f2/88/c3a94f65b527aa4631426bed957add0e4e0bcc531a9686ff1cb73fc5efab/pymmcore_plus-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d64050023cff76ee31860b361f2bf49095096e3b5776ec192a70d37be8694aba",
"md5": "4c2efbff26ccdf3b756014166eabe5e9",
"sha256": "9971d596ffc6357a6f42b1193be3c8abd6ef786ab308ffeb8d13ca35785c5286"
},
"downloads": -1,
"filename": "pymmcore_plus-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "4c2efbff26ccdf3b756014166eabe5e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 139704,
"upload_time": "2024-10-05T15:26:50",
"upload_time_iso_8601": "2024-10-05T15:26:50.172850Z",
"url": "https://files.pythonhosted.org/packages/d6/40/50023cff76ee31860b361f2bf49095096e3b5776ec192a70d37be8694aba/pymmcore_plus-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-05 15:26:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pymmcore-plus",
"github_project": "pymmcore-plus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymmcore-plus"
}
JSON
