camera-alignment-core#

Core algorithms for aligning two-camera microscopy imagery

Installation#

pip install camera_alignment_core==1.0.6

This library is published to a private PyPI server on AWS CodeArtifact accessible within the Allen Institute network or over VPN. This has downstream effects for how this library is installed into other Python packages.

Documentation#

The primary export of this package is the Align class. It provides a convenient abstraction over what is expected to be the most common usage of this package. Example use:

from camera_alignment_core import Align, Magnification
from camera_alignment_core.channel_info import channel_info_factory, CameraPosition


biological_data_to_align_path = "/some/path/to/an/image.czi"
optical_control_path = "/some/path/to/an/argolight-field-of-rings.czi"

# `Align` is the root, coordinating entity, that encapsulates all of the steps to:
#   1. Generate a similarity transformation matrix;
#   2. Apply that matrix to a (potentially) multi-scene, (potentially) multi-timepoint biological image;
#   3. Apply that matrix to the optical_control itself
#       (e.g., to produce a reference alignment that can be consulted to assess alignment quality).
#
# This snippet shows using only the required parameters, but `Align` also takes optional keyword arguments
# for specifying which channels within `optical_control` to treat as the
# reference and the shift for the purpose of producing the similarity transformation matrix.
# See `Align`'s documentation for details on the default behavior if these optional arguments
# are not provided.
align = Align(
    optical_control=optical_control_path,
    magnification=Magnification(20),
    out_dir="/tmp/whereever",
)

# If you don't already have a list of channel indices that you know should be shifted
# during alignment, consider using the `ChannelInfo` utility. Note:
#   1. You must construct a `ChannelInfo` using the `channel_info_factory`.
#   2. Currently, only CZI files are supported by this utility.
biological_data_channel_info = channel_info_factory(biological_data_to_align_path)

# ...`ChannelInfo` offers convenience methods for identifying an image's channels.
# For example, identifying which were acquired on the back camera (e.g.: Brightfield, CMDRP).
biological_data_back_channels = biological_data_channel_info.channels_from_camera_position(
    CameraPosition.BACK
)

# `Align::align_image` returns a list of info objects (`AlignedImage`) pointing at the output of the method.
# These info objects have two properties:
#   1. scene : the scene index from the image that this newly aligned image is from; and
#   2. path : the filesystem path to the aligned scene. The base path is the `out_dir` you
#       specified in the `Align` constructor.
# If the image you're aligning is single-scene, this will be a list of one `AlignedImage`.
aligned_scenes = align.align_image(
    image_to_align_path,
    channels_to_shift=[channel.channel_index for channel in biological_data_back_channels]
)

# ...(Right now in the script would be a great time to iterate over `aligned_scenes` and
# upload each aligned scene to FMS and delete the now unnecessary versions saved in `out_dir`.
# Refer to aicsfiles documentation should you need help with uploading.)...

# You can also use `Align` to create a reference alignment by aligning the optical control
# image itself. This may be helpful, for example, to spot check alignnment quality.
optical_control_channel_info = channel_info_factory(optical_control_path)
optical_control_back_channels = optical_control_channel_info.channels_from_camera_position(
    CameraPosition.BACK
)
aligned_optical_control = align.align_optical_control(
    channels_to_shift=[channel.channel_index for channel in optical_control_back_channels]
)

# `Align` also provides access to certain details from the alignment process,
# including the similarity transformation matrix itself, as well as summary information
# gathered while producing that matrix (see documentation for `AlignmentInfo` for more details).
alignment_matrix = align.alignment_transform.matrix
alignment_info = align.alignment_transform.info

Low-level API#

In addition, the lower-level functional building blocks used internally by Align are accessible in the camera_alignment_core.alignment_core module. See:

  1. align_image

  2. apply_alignment_matrix

  3. crop

  4. generate_alignment_matrix

Development#

This repository uses make as a task runner. Various make commands/targets have been written to automate the setup of a local development environment, run quality assurance tests, build and distribute the library. The following are notable make targets; see Makefile for others or to inspect the underlying scripts run as part of these targets:

  1. make install:

    This will setup a virtual environment local to this project and install all of the project’s dependencies into it. The virtual env will be located in camera-alignment-core/venv.

  2. Quality assurance make tasks:

    After running make install, a git pre-commit hook will be installed in your local .git/hooks. This pre-commit hook is managed by pre-commit, configured in .pre-commit-config.yaml. These commit hooks will ensure QA is run on your code before you commit it. The code formatters that are run on pre-commit have side-effects; if they don’t exit successfully, they will modify your staged files, and you will need to stage the new changes.

    1. make lint: Linting using flake8

    2. make type-check: Static analysis using mypy

    3. make fmt: Auto-code formatting using black

    #. make import-sort: Auto-import sorting using isort #.

    make test: Programmatic tests, run with pytest

    Code is not ready to merge until all of these QA tests pass.

  3. make clean:

    This will clean up various Python and build generated files so that you can ensure that you are working in a clean workspace. This, in combination with make install, should be the first thing you do if your branch is building locally but failing in CI.

  4. Releases:

    Releasing fixes requires more than merging to main.

    1. everything in step 2 above: (eg, make lint type-check fmt import-sort )

    2. make doc: (to confirm the docs build)

    3. make publish: to publish to CodeArtifact. Requires a ~/.pypirc file with an entry like:

      [release-local] repository = https://production-239877123246.d.codeartifact.us-west-2.amazonaws.com/pypi/pypi-release-local/

    4. Update the example-venv lockfile to use the new release.

      1. Install uv

      2. cd example-venv && uv lock && uv sync

      3. uv pip list | grep camera-alignment-core (This should show the new version.)

Allen Institute Software License

Indices and tables#