# camacq [](https://github.com/CellProfiling/cam_acq/actions) [](http://cam-acq.readthedocs.io/en/latest/?badge=latest)
Python project to control microscope through client-server program.
## Install
- Install the camacq package. Python version 3.10+ is supported.
```sh
# Check python version.
python --version
# Install package.
pip install camacq
# Test that program is callable and show help.
camacq -h
```
## Run
```sh
camacq
```
## Configure
camacq uses a yaml configuration file, config.yml, for configuring
almost all settings in the app. The configuration file is found in the
configuration directory. The default configuration directory is located
in the home directory and called `.camacq`.
The location of the configuration directory can be overridden when
starting camacq.
```sh
camacq --config /my_custom_config_dir
```
When camacq is started it checks the configuration directory for the
configuration file, and if none is found creates a default configuration
file. See below for an example of how to configure the leica api and a
simple automation, in the configuration yaml file.
```yaml
leica:
host: localhost
port: 8895
imaging_dir: '/imaging_dir'
automations:
- name: start
trigger:
- type: event
id: camacq_start_event
action:
- type: command
id: start_imaging
```
## API
To interact with a microscope camacq needs to connect to an API from a
microscope vendor, which in turn will control the microscope. Currently
camacq can connect to the Computer Aided Microscopy (CAM) interface of
Leica Microsystems' microscopes that have that feature activated. The
design of camacq is built to be able to easily extend to APIs of other
microscope vendors in the future. We welcome pull requests for this and
other improvements. The API interface should be contained within a
separate Python library, that instantiates a client object which camacq
can use.
```yaml
leica:
host: localhost
port: 8895
imaging_dir: '/imaging_dir'
```
## Automations
To tell the microscope what to do, camacq uses automations. Automations
are blocks of yaml consisting of triggers, optional conditions and
actions. A trigger is the notification of an event in camacq, eg a new
image is saved. An action is what camacq should do when the trigger
triggers, eg go to the next well. A condition is a criteria that has to
be true to allow the action to execute, when a trigger has triggered.
As events happen, camacq checks the configured automations to see if any
automation trigger matches the event. If there is a match, it also
checks for possible conditions and if they are true. If both trigger and
conditions matches and resolves to true, the corresponding action(s)
will be executed.
For each automation block, it is possible to have multiple triggers,
multiple conditions and multiple actions. Eg we can configure an
automation with two triggers and two actions. If any of the triggers
matches an event, both actions will be executed, in sequence.
```yaml
automations:
name: image_next_well
trigger:
- type: event
id: camacq_start_event
- type: event
id: well_event
data:
well_img_ok: true
action:
- type: sample
id: set_sample
data:
plate_name: plate_1
well_x: 1
well_y: >
{{ trigger.event.well_y + 1 }}
- type: command
id: start_imaging
```
### Trigger
Let us look more closely at the trigger section of the above automation.
```yaml
trigger:
- type: event
id: camacq_start_event
- type: event
id: well_event
data:
well_img_ok: true
```
This section now holds a sequence of two trigger items, where each has a
type and an id. The second item also has a `data` key. The
`type` key tells camacq what type of trigger it should
configure. Currently only triggers of type `event` are
available. See the [documentation](http://cam-acq.readthedocs.io) for
all available event ids. The `id` key sets the trigger id
which will be the first part of the matching criteria for the trigger.
The second part is optional and is the value of the `data`
key. This key can hold key-value pairs with event data that should match
the attributes of the event for the trigger to trigger. So for the
second item we want the event to have id `well_event` and
to have an attribute called `well_img_ok` which should
return `True`, for the event to trigger our trigger.
### Action
Looking at the action section of our example automation, we see that it
also has two items. And exactly as for the triggers, each action has a
`type` and an `id`, and can optionally specify
a `data` key. Actions can have different types, eg
`sample` or `command`. You will find all of
the action types in the [documentation](http://cam-acq.readthedocs.io).
For an action, the `data` key sets the keyword arguments
that should be provided to the action handler function that executes the
action.
```yaml
action:
- type: sample
id: set_sample
data:
plate_name: plate_1
well_x: 1
well_y: >
{{ trigger.event.well_y + 1 }}
- type: command
id: start_imaging
```
In our example we want to do two things, first set a well, and then
start the imaging. To not have to define this automation for each well
we want to image, automations allow for dynamic rendering of the value
of a data key, via use of the [Jinja2](http://jinja.pocoo.org/docs)
template language. You can recognize this part by the curly brackets.
See the template section below for further details.
### Template
Using templates in automations allows us to build powerful and flexible
pieces of automation configuration code to control the microscope.
Besides having all the standard Jinja2 features, we also have the
trigger event and the full sample state data available as variables when
the template is rendered. Eg if a well event triggered the automation we
can use `trigger.event.container` inside the template and have
access to all the attributes of the well container that triggered the event.
Useful sample attributes are also directly available on the
`trigger.event` eg `trigger.event.well_x`.
```yaml
well_y: >
{% if trigger.event.container is defined %}
{{ trigger.event.well_y + 1 }}
{% else %}
1
{% endif %}
```
If we need access to some sample state that isn't part of the trigger,
we can use `samples` directly in the template. Via this
variable the whole sample state data is accessible from inside a
template. See below for the sample attribute structure. Note that only
condition and action values in key-value pairs support rendering a
template. Templates are not supported in the keys of key-value pairs and
not in trigger sections.
### Condition
A condition can be used to check the current sample state and only
execute the action if some criteria is met. Say eg we want to make sure
that channel 3 of well 1:1 of plate 1 is green and that gain is set to
800.
```yaml
condition:
type: AND
conditions:
- condition: >
{% if samples.leica.data['{"name": "channel", "plate_name": "plate_1", "well_x": 1, "well_y": 1, "channel_id": 3}'].values['channel_name'] == 'green' %}
true
{% endif %}
- condition: >
{% if samples.leica.data['{"name": "channel", "plate_name": "plate_1", "well_x": 1, "well_y": 1, "channel_id": 3}'].values['gain'] == 800 %}
true
{% endif %}
```
The trigger event data is also available in the condition template as a
variable. Below example will evaluate to true if the well that triggered
the event has either 1 or 2 as x coordinate.
```yaml
condition:
type: OR
conditions:
- condition: >
{% if trigger.event.well_x == 1 %}
true
{% endif %}
- condition: >
{% if trigger.event.well_x == 2 %}
true
{% endif %}
```
Currently each condition must be a template that renders to the string
`true` if the condition criteria is met.
## Sample
The sample state should represent the sample with a representation that
is specific to each implemented microscope api using the `ImageContainer`
api of camacq. An image container has a `name`, a dictionary of `images` and
a dictionary of `values` as attributes. The container also fires a specific
event on container change.
There are two special cases of the image container. The first is the main
sample container of each microscope api, eg the leica container. The main
container has an extra attribute `data` which is a dictionary with all the
containers of the sample. The second special case is the image in the
dictionary of images of an image container. The image is also a container
and has only itself in the images dictionary and a `path` attribute with
the path of the image.
Eg for the leica sample there are plate, well, field, z_slice, channel and
image containers under the main leica sample container.
All implemented sample states are available as a variable `samples` in
templates in automations. The leica sample is available as `samples.leica`.
See below for the leica sample state attribute structure in camacq.
The words in all capital letters are example values. Each image container
has a name, which is either of plate, well, field, z_slice, channel or image.
The different leica containers have different leica specific attributes
that aren't all shown below.
```yaml
samples:
leica:
name: leica
images:
PATH:
name: image
path: PATH
plate_name: PLATE_NAME
well_x: WELL_X
well_y: WELL_Y
field_x: FIELD_X
field_y: FIELD_Y
z_slice_id: Z_SLICE_ID
channel_id: CHANNEL_ID
images:
PATH: self
values:
VALUE_KEY: VALUE
values:
VALUE_KEY: VALUE
data:
CONTAINER_ID:
name: plate/well/field/z_slice/channel/image
images:
PATH:
name: image
path: PATH
plate_name: PLATE_NAME
well_x: WELL_X
well_y: WELL_Y
field_x: FIELD_X
field_y: FIELD_Y
z_slice_id: Z_SLICE_ID
channel_id: CHANNEL_ID
images:
PATH: self
values:
VALUE_KEY: VALUE
values:
VALUE_KEY: VALUE
```
## Plugins
To extend the functionality of camacq and to make it possible to do
automated feedback microscopy, camacq supports plugins. A plugin is a
module or a package in camacq that provides code for a specific task. It
can eg be an image analysis script. See the
[documentation](http://cam-acq.readthedocs.io) for all default available
plugins.
To install a custom plugin, create a Python package with a `setup.py` module that
implements the entry_points interface with key `"camacq.plugins"`.
```py
setup(
...
entry_points={"camacq.plugins": "plugin_a = package_a.plugin_a"},
...
)
```
See the packaging [docs](https://packaging.python.org/guides/creating-and-discovering-plugins/#using-package-metadata) for details.
`camacq` will
automatically load installed modules or packages that implement this entry_point.
Add a `setup_module` coroutine function in the module or package. This function
will be awaited with `center` and `config` as arguments.
```py
async def setup_module(center, config):
"""Set up the plugin package."""
```
Each plugin must have its own configuration section at the root of the config.
```yaml
example_plugin:
...
```
## Development
Install the packages needed for development.
```sh
pip install -r requirements_dev.txt
```
Use the Makefile to run common development tasks.
```sh
make
```
### Release
See the [release instructions](RELEASE.md).
## Credits
A lot of the inspiration for the architecture of camacq comes from
another open-source Python automation app: [Home
Assistant](https://github.com/home-assistant/home-assistant). This is
also the source for the automations interface in camacq.
Raw data
{
"_id": null,
"home_page": "https://github.com/CellProfiling/cam_acq",
"name": "camacq",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Martin Hjelmare",
"author_email": "marhje52@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6b/a0/c87bb856c737d88c5a4fc70cbb21f489bf6214d426c63526331b156e9a44/camacq-0.8.0.tar.gz",
"platform": null,
"description": "# camacq [](https://github.com/CellProfiling/cam_acq/actions) [](http://cam-acq.readthedocs.io/en/latest/?badge=latest)\n\nPython project to control microscope through client-server program.\n\n## Install\n\n- Install the camacq package. Python version 3.10+ is supported.\n\n ```sh\n # Check python version.\n python --version\n # Install package.\n pip install camacq\n # Test that program is callable and show help.\n camacq -h\n ```\n\n## Run\n\n```sh\ncamacq\n```\n\n## Configure\n\ncamacq uses a yaml configuration file, config.yml, for configuring\nalmost all settings in the app. The configuration file is found in the\nconfiguration directory. The default configuration directory is located\nin the home directory and called `.camacq`.\n\nThe location of the configuration directory can be overridden when\nstarting camacq.\n\n```sh\ncamacq --config /my_custom_config_dir\n```\n\nWhen camacq is started it checks the configuration directory for the\nconfiguration file, and if none is found creates a default configuration\nfile. See below for an example of how to configure the leica api and a\nsimple automation, in the configuration yaml file.\n\n```yaml\nleica:\n host: localhost\n port: 8895\n imaging_dir: '/imaging_dir'\n\nautomations:\n - name: start\n trigger:\n - type: event\n id: camacq_start_event\n action:\n - type: command\n id: start_imaging\n```\n\n## API\n\nTo interact with a microscope camacq needs to connect to an API from a\nmicroscope vendor, which in turn will control the microscope. Currently\ncamacq can connect to the Computer Aided Microscopy (CAM) interface of\nLeica Microsystems' microscopes that have that feature activated. The\ndesign of camacq is built to be able to easily extend to APIs of other\nmicroscope vendors in the future. We welcome pull requests for this and\nother improvements. The API interface should be contained within a\nseparate Python library, that instantiates a client object which camacq\ncan use.\n\n```yaml\nleica:\n host: localhost\n port: 8895\n imaging_dir: '/imaging_dir'\n```\n\n## Automations\n\nTo tell the microscope what to do, camacq uses automations. Automations\nare blocks of yaml consisting of triggers, optional conditions and\nactions. A trigger is the notification of an event in camacq, eg a new\nimage is saved. An action is what camacq should do when the trigger\ntriggers, eg go to the next well. A condition is a criteria that has to\nbe true to allow the action to execute, when a trigger has triggered.\n\nAs events happen, camacq checks the configured automations to see if any\nautomation trigger matches the event. If there is a match, it also\nchecks for possible conditions and if they are true. If both trigger and\nconditions matches and resolves to true, the corresponding action(s)\nwill be executed.\n\nFor each automation block, it is possible to have multiple triggers,\nmultiple conditions and multiple actions. Eg we can configure an\nautomation with two triggers and two actions. If any of the triggers\nmatches an event, both actions will be executed, in sequence.\n\n```yaml\nautomations:\n name: image_next_well\n trigger:\n - type: event\n id: camacq_start_event\n - type: event\n id: well_event\n data:\n well_img_ok: true\n action:\n - type: sample\n id: set_sample\n data:\n plate_name: plate_1\n well_x: 1\n well_y: >\n {{ trigger.event.well_y + 1 }}\n - type: command\n id: start_imaging\n```\n\n### Trigger\n\nLet us look more closely at the trigger section of the above automation.\n\n```yaml\ntrigger:\n - type: event\n id: camacq_start_event\n - type: event\n id: well_event\n data:\n well_img_ok: true\n```\n\nThis section now holds a sequence of two trigger items, where each has a\ntype and an id. The second item also has a `data` key. The\n`type` key tells camacq what type of trigger it should\nconfigure. Currently only triggers of type `event` are\navailable. See the [documentation](http://cam-acq.readthedocs.io) for\nall available event ids. The `id` key sets the trigger id\nwhich will be the first part of the matching criteria for the trigger.\nThe second part is optional and is the value of the `data`\nkey. This key can hold key-value pairs with event data that should match\nthe attributes of the event for the trigger to trigger. So for the\nsecond item we want the event to have id `well_event` and\nto have an attribute called `well_img_ok` which should\nreturn `True`, for the event to trigger our trigger.\n\n### Action\n\nLooking at the action section of our example automation, we see that it\nalso has two items. And exactly as for the triggers, each action has a\n`type` and an `id`, and can optionally specify\na `data` key. Actions can have different types, eg\n`sample` or `command`. You will find all of\nthe action types in the [documentation](http://cam-acq.readthedocs.io).\nFor an action, the `data` key sets the keyword arguments\nthat should be provided to the action handler function that executes the\naction.\n\n```yaml\naction:\n - type: sample\n id: set_sample\n data:\n plate_name: plate_1\n well_x: 1\n well_y: >\n {{ trigger.event.well_y + 1 }}\n - type: command\n id: start_imaging\n```\n\nIn our example we want to do two things, first set a well, and then\nstart the imaging. To not have to define this automation for each well\nwe want to image, automations allow for dynamic rendering of the value\nof a data key, via use of the [Jinja2](http://jinja.pocoo.org/docs)\ntemplate language. You can recognize this part by the curly brackets.\nSee the template section below for further details.\n\n### Template\n\nUsing templates in automations allows us to build powerful and flexible\npieces of automation configuration code to control the microscope.\nBesides having all the standard Jinja2 features, we also have the\ntrigger event and the full sample state data available as variables when\nthe template is rendered. Eg if a well event triggered the automation we\ncan use `trigger.event.container` inside the template and have\naccess to all the attributes of the well container that triggered the event.\nUseful sample attributes are also directly available on the\n`trigger.event` eg `trigger.event.well_x`.\n\n```yaml\nwell_y: >\n {% if trigger.event.container is defined %}\n {{ trigger.event.well_y + 1 }}\n {% else %}\n 1\n {% endif %}\n```\n\nIf we need access to some sample state that isn't part of the trigger,\nwe can use `samples` directly in the template. Via this\nvariable the whole sample state data is accessible from inside a\ntemplate. See below for the sample attribute structure. Note that only\ncondition and action values in key-value pairs support rendering a\ntemplate. Templates are not supported in the keys of key-value pairs and\nnot in trigger sections.\n\n### Condition\n\nA condition can be used to check the current sample state and only\nexecute the action if some criteria is met. Say eg we want to make sure\nthat channel 3 of well 1:1 of plate 1 is green and that gain is set to\n800.\n\n```yaml\ncondition:\n type: AND\n conditions:\n - condition: >\n {% if samples.leica.data['{\"name\": \"channel\", \"plate_name\": \"plate_1\", \"well_x\": 1, \"well_y\": 1, \"channel_id\": 3}'].values['channel_name'] == 'green' %}\n true\n {% endif %}\n - condition: >\n {% if samples.leica.data['{\"name\": \"channel\", \"plate_name\": \"plate_1\", \"well_x\": 1, \"well_y\": 1, \"channel_id\": 3}'].values['gain'] == 800 %}\n true\n {% endif %}\n```\n\nThe trigger event data is also available in the condition template as a\nvariable. Below example will evaluate to true if the well that triggered\nthe event has either 1 or 2 as x coordinate.\n\n```yaml\ncondition:\n type: OR\n conditions:\n - condition: >\n {% if trigger.event.well_x == 1 %}\n true\n {% endif %}\n - condition: >\n {% if trigger.event.well_x == 2 %}\n true\n {% endif %}\n```\n\nCurrently each condition must be a template that renders to the string\n`true` if the condition criteria is met.\n\n## Sample\n\nThe sample state should represent the sample with a representation that\nis specific to each implemented microscope api using the `ImageContainer`\napi of camacq. An image container has a `name`, a dictionary of `images` and\na dictionary of `values` as attributes. The container also fires a specific\nevent on container change.\n\nThere are two special cases of the image container. The first is the main\nsample container of each microscope api, eg the leica container. The main\ncontainer has an extra attribute `data` which is a dictionary with all the\ncontainers of the sample. The second special case is the image in the\ndictionary of images of an image container. The image is also a container\nand has only itself in the images dictionary and a `path` attribute with\nthe path of the image.\n\nEg for the leica sample there are plate, well, field, z_slice, channel and\nimage containers under the main leica sample container.\n\nAll implemented sample states are available as a variable `samples` in\ntemplates in automations. The leica sample is available as `samples.leica`.\n\nSee below for the leica sample state attribute structure in camacq.\nThe words in all capital letters are example values. Each image container\nhas a name, which is either of plate, well, field, z_slice, channel or image.\nThe different leica containers have different leica specific attributes\nthat aren't all shown below.\n\n```yaml\nsamples:\n leica:\n name: leica\n images:\n PATH:\n name: image\n path: PATH\n plate_name: PLATE_NAME\n well_x: WELL_X\n well_y: WELL_Y\n field_x: FIELD_X\n field_y: FIELD_Y\n z_slice_id: Z_SLICE_ID\n channel_id: CHANNEL_ID\n images:\n PATH: self\n values:\n VALUE_KEY: VALUE\n values:\n VALUE_KEY: VALUE\n data:\n CONTAINER_ID:\n name: plate/well/field/z_slice/channel/image\n images:\n PATH:\n name: image\n path: PATH\n plate_name: PLATE_NAME\n well_x: WELL_X\n well_y: WELL_Y\n field_x: FIELD_X\n field_y: FIELD_Y\n z_slice_id: Z_SLICE_ID\n channel_id: CHANNEL_ID\n images:\n PATH: self\n values:\n VALUE_KEY: VALUE\n values:\n VALUE_KEY: VALUE\n```\n\n## Plugins\n\nTo extend the functionality of camacq and to make it possible to do\nautomated feedback microscopy, camacq supports plugins. A plugin is a\nmodule or a package in camacq that provides code for a specific task. It\ncan eg be an image analysis script. See the\n[documentation](http://cam-acq.readthedocs.io) for all default available\nplugins.\n\nTo install a custom plugin, create a Python package with a `setup.py` module that\nimplements the entry_points interface with key `\"camacq.plugins\"`.\n\n```py\nsetup(\n ...\n entry_points={\"camacq.plugins\": \"plugin_a = package_a.plugin_a\"},\n ...\n)\n```\n\nSee the packaging [docs](https://packaging.python.org/guides/creating-and-discovering-plugins/#using-package-metadata) for details.\n\n`camacq` will\nautomatically load installed modules or packages that implement this entry_point.\n\nAdd a `setup_module` coroutine function in the module or package. This function\nwill be awaited with `center` and `config` as arguments.\n\n```py\nasync def setup_module(center, config):\n \"\"\"Set up the plugin package.\"\"\"\n```\n\nEach plugin must have its own configuration section at the root of the config.\n\n```yaml\nexample_plugin:\n ...\n```\n\n## Development\n\nInstall the packages needed for development.\n\n```sh\npip install -r requirements_dev.txt\n```\n\nUse the Makefile to run common development tasks.\n\n```sh\nmake\n```\n\n### Release\n\nSee the [release instructions](RELEASE.md).\n\n## Credits\n\nA lot of the inspiration for the architecture of camacq comes from\nanother open-source Python automation app: [Home\nAssistant](https://github.com/home-assistant/home-assistant). This is\nalso the source for the automations interface in camacq.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Control microscope through client server program.",
"version": "0.8.0",
"project_urls": {
"Download": "https://github.com/CellProfiling/cam_acq/archive/master.zip",
"Homepage": "https://github.com/CellProfiling/cam_acq"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "830a30b1f41d2fdd614c1b4ce1cb12979e7e68d5c874ff4628c271856af0f621",
"md5": "db550c74a0447f7715195196b6cf9932",
"sha256": "ea0c4c480b2f3d2e7fcfdae7a7e9e9d2af3de9646cb1fa88f977e079614c2755"
},
"downloads": -1,
"filename": "camacq-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db550c74a0447f7715195196b6cf9932",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 43175,
"upload_time": "2024-12-28T10:39:41",
"upload_time_iso_8601": "2024-12-28T10:39:41.962600Z",
"url": "https://files.pythonhosted.org/packages/83/0a/30b1f41d2fdd614c1b4ce1cb12979e7e68d5c874ff4628c271856af0f621/camacq-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6ba0c87bb856c737d88c5a4fc70cbb21f489bf6214d426c63526331b156e9a44",
"md5": "69bac4a5e34eb1b75a62c48d39e05a0d",
"sha256": "4868b056b8fa1c45c276555a9407e847d9082f2e0f7067c4f276476856a0b282"
},
"downloads": -1,
"filename": "camacq-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "69bac4a5e34eb1b75a62c48d39e05a0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 39476,
"upload_time": "2024-12-28T10:39:44",
"upload_time_iso_8601": "2024-12-28T10:39:44.043123Z",
"url": "https://files.pythonhosted.org/packages/6b/a0/c87bb856c737d88c5a4fc70cbb21f489bf6214d426c63526331b156e9a44/camacq-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-28 10:39:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CellProfiling",
"github_project": "cam_acq",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "async_timeout",
"specs": [
[
"==",
"5.0.1"
]
]
},
{
"name": "colorlog",
"specs": [
[
"==",
"6.9.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
"==",
"3.1.5"
]
]
},
{
"name": "leicacam",
"specs": [
[
"==",
"0.4.2"
]
]
},
{
"name": "leicaimage",
"specs": [
[
"==",
"0.4.0"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.2.1"
]
]
},
{
"name": "ruamel.yaml",
"specs": [
[
"==",
"0.18.6"
]
]
},
{
"name": "tifffile",
"specs": [
[
"==",
"2024.12.12"
]
]
},
{
"name": "voluptuous",
"specs": [
[
"==",
"0.15.2"
]
]
},
{
"name": "xmltodict",
"specs": [
[
"==",
"0.14.2"
]
]
}
],
"tox": true,
"lcname": "camacq"
}
JSON
