camacq

Python项目，通过客户端服务器程序控制显微镜。

安装

• 安装camacq软件包。支持Python版本3.6以上。

  # Check python version.
  python --version
  # Install package.
  pip install camacq
  # Test that program is callable and show help.
  camacq -h
  

运行

camacq

配置

camacq使用yaml配置文件config.yml来配置应用中几乎所有设置。配置文件位于配置目录中。默认配置目录位于主目录中，名为.camacq。

在启动camacq时可以覆盖配置目录的位置。

camacq --config /my_custom_config_dir

当camacq启动时，它会检查配置目录中的配置文件，如果找不到，则创建一个默认配置文件。以下是如何在配置yaml文件中配置leica api和一个简单的自动化的示例。

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

要与显微镜进行交互，camacq需要连接到显微镜制造商的API，进而控制显微镜。目前，camacq可以连接到具有该功能的莱卡显微镜的计算机辅助显微镜（CAM）接口。camacq的设计旨在能够轻松扩展到未来其他显微镜制造商的API。我们欢迎对此以及其他改进的pull requests。API接口应包含在一个单独的Python库中，该库实例化一个客户端对象，camacq可以使用。

leica:
  host: localhost
  port: 8895
  imaging_dir: '/imaging_dir'

自动化

为了告诉显微镜做什么，camacq使用自动化。自动化由yaml块组成，包含触发器、可选条件和操作。触发器是camacq中事件的通告，例如新图像已保存。操作是触发器触发时camacq应该执行的操作，例如转到下一个孔。条件是一个必须为真才能允许操作执行的准则，当触发器触发时。

随着事件的发生，camacq检查配置的自动化，看是否有任何自动化触发器与事件匹配。如果存在匹配，它还会检查可能的条件，并查看它们是否为真。如果触发器和条件都匹配并解析为真，则将执行相应的操作。

对于每个自动化块，可以具有多个触发器、多个条件和多个操作。例如，我们可以配置一个具有两个触发器和两个操作的自动化。如果任何触发器与事件匹配，则两个操作将按顺序执行。

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:
  - type: event
    id: camacq_start_event
  - type: event
    id: well_event
    data:
      well_img_ok: true

该部分现在包含两个触发项的序列，其中每个项都有一个类型和一个ID。第二个项还有一个data键。type键告诉camacq应该配置什么类型的触发器。目前，只有类型为event的触发器可用。请参阅文档以获取所有可用的事件ID。id键设置触发器ID，它将是触发器匹配准则的第一部分。第二部分是可选的，是data键的值。此键可以包含应与触发器的事件属性匹配的事件数据的键值对。因此，对于第二个项，我们希望事件具有ID well_event，并且具有一个名为well_img_ok的属性，该属性应返回True，以便触发我们的触发器。

操作

查看我们示例自动化中的操作部分，我们看到它也有两个项。就像触发器一样，每个操作都有一个type和id，并且可以可选地指定一个data键。操作可以有不同类型，例如sample或command。您将在文档中找到所有操作类型。data键为执行操作的action处理器函数设置关键字参数。

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

在我们的示例中，我们想做两件事，首先设置一个孔，然后开始成像。为了避免为每个要成像的孔定义此自动化，自动化允许使用Jinja2模板语言动态渲染数据键的值。您可以通过花括号识别这一部分。请参阅下面的模板部分以获取更多详细信息。

模板

在自动化中使用模板可以让我们构建强大的、灵活的自动化配置代码，以控制显微镜。除了拥有所有标准的 Jinja2 功能外，在模板渲染时，我们还可用作变量访问触发事件和完整的样本状态数据。例如，如果一个井事件触发了自动化，我们可以在模板中使用 trigger.event.container 并访问触发事件的井容器的所有属性。有用的样本属性也直接在 trigger.event 上可用，例如 trigger.event.well_x。

well_y: >
  {% if trigger.event.container is defined %}
    {{ trigger.event.well_y + 1 }}
  {% else %}
    1
  {% endif %}

如果我们需要访问触发事件中不包含的某些样本状态，我们可以在模板中直接使用 samples。通过这个变量，可以访问模板内的整个样本状态数据。下面是样本属性结构的示例。注意，只有键值对中的条件和动作值支持渲染模板。模板不支持在键值对的键或触发部分中。

条件

条件可以用来检查当前样本状态，并且只有当满足某些标准时才执行动作。例如，我们想要确保1号板1:1号井的通道3是绿色，增益设置为800。

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 %}

触发事件数据也作为变量在条件模板中可用。以下示例将评估为真，如果触发事件的井具有1或2作为x坐标。

condition:
  type: OR
  conditions:
    - condition: >
        {% if trigger.event.well_x == 1 %}
          true
        {% endif %}
    - condition: >
        {% if trigger.event.well_x == 2 %}
          true
        {% endif %}

目前，每个条件都必须是一个渲染到字符串 true 的模板，如果条件标准得到满足。

样本

样本状态应该使用 camacq 的 ImageContainer api 通过对每个实现的显微镜 api 使用特定的表示来表示样本。一个图像容器具有一个 name、一个包含 images 的字典和一个包含 values 的字典作为属性。容器还会在容器更改时触发特定的事件。

图像容器有两种特殊情况。第一种是每个显微镜 api 的主样本容器，例如 leica 容器。主容器有一个额外的属性 data，它是一个包含所有容器的字典。第二种特殊情况是图像容器中图像字典中的图像。图像也是一个容器，它在图像字典中只有自身，并且有一个 path 属性，包含图像的路径。

例如，对于 leica 样本，在主 leica 样本容器下有板、井、字段、z_slice、通道和图像容器。

所有实现的样本状态都作为变量 samples 在自动化模板中可用。leica 样本作为 samples.leica 可用。

以下是在 camacq 中 leica 样本状态属性结构的示例。所有大写字母的词都是示例值。每个图像容器都有一个名称，该名称是板、井、字段、z_slice、通道或图像之一。不同的 leica 容器有不同的 leica 特定属性，下面没有全部显示。

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

插件

为了扩展 camacq 的功能，并使其能够进行自动反馈显微镜操作，camacq 支持插件。插件是 camacq 中的一个模块或包，它为特定任务提供代码。例如，它可以是图像分析脚本。请参阅文档以获取所有默认可用的插件的详细信息。

要安装自定义插件，创建一个包含实现 entry_points 接口且键为 "camacq.plugins" 的 setup.py 模块的 Python 包。

setup(
    ...
    entry_points={"camacq.plugins": "plugin_a = package_a.plugin_a"},
    ...
)

请参阅文档以获取详细信息。

camacq 将自动加载实现此 entry_point 的已安装模块或包。

在模块或包中添加一个 setup_module 协程函数。此函数将使用 center 和 config 作为参数进行等待。

async def setup_module(center, config):
    """Set up the plugin package."""

每个插件必须在配置的根目录下有自己的配置部分。

example_plugin:
  ...

开发

安装开发所需的包。

pip install -r requirements_dev.txt

使用 Makefile 运行常见的开发任务。

make

发布

请参阅发布说明。

致谢

camacq架构的许多灵感来源于另一个开源Python自动化应用程序：Home Assistant。这也是camacq自动化界面的来源。