Installing Python code

The following components of Spotlight's control/data acquisition code are written in Python:

• Generating the ArUco board for calibration (see Calibration algorithm)
• Fitting the affine linear calibration models (see Calibration algorithm)
• Post-processing recording data: (merging scattered metadata, merging individual images into a video, generating visualization for motion stages' trajectory, etc.)

These code are saved under the tools directory. We use Poetry for package management. Unlike other package managers like pip or Conda, Poetry generates a detailed poetry.lock file that precisely pins every dependency and sub-dependency to specific versions, ensuring truly reproducible builds across all environments. It creates and manages virtual environments automatically and simplifies the packaging and distribution process with built-in commands for building and publishing.

Follow the steps below to install the Python code:

1. Follow Poetry's official installation guide. This might involve installing pipx first.
2. Change into the tools directory: cd spotlight-control/tools.
3. Install the dependencies using Poetry: poetry install

Every time you need to run Python tools, you can activate the virtual environment by first cd-ing into spotlight-control/tools and then running eval $(poetry env activate). Then, you should be able to run the command line tools directly from your shell. For example:

username@hostname:~/project/spotlight-control$ generate-calibration-board --help
usage: generate-calibration-board [-h] [OPTIONS]

Generate an ArUco board with the specified parameters.

╭─ options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit                                                               │
│ --arena-size-x-mm FLOAT                                                                                               │
│                         The width of the arena in mm. (default: 48)                                                   │
│ --arena-size-y-mm FLOAT                                                                                               │
│                         The height of the arena in mm. (default: 72)                                                  │
│ --aruco-scale-mm FLOAT  Side length of each square (i.e. "pixel") inside each aruco                                   │
│                         code (mm). (default: 0.3)                                                                     │
│ --aruco-spacing-unitblk INT                                                                                           │
│                         Space between each two aruco codes (in squres, i.e. "pixels"). (default: 2)                   │
│ --output-path STR       The path to save the generated SVG file. (default: '~/Spotlight/aruco_board/aruco_board.svg') │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

These scripts are actually under tools/src/spotlight_tools/scripts but are exposed as CLI commands using Poetry. See the [tool.poetry.scripts] section of the pyproject.toml file for details.

For maintainers

Occasionally, the maintainer should run poetry lock to update the dependency versions pinned in poetry.lock. To do so:

1. Make a backup of the latest working poetry.lock file.
2. Manually check if the version specifications in pyproject.toml are still reasonable. Bump up the versions if needed. Note that following semantic versioning, all packages under initial development (i.e. with version numbers 0.x.x) are pinned to the exact version, as they can have API-breaking changes at any time. You might want to update these in particular.
3. Run poetry lock to update the poetry.lock file based on (i) the updated version specification in pyproject.toml and (ii) what has become available on PyPI since the last "lock."
4. Manually verify if everything is still working. In case of any version conflict, fix them and update pyproject.toml accordingly. Then repeat this process.
5. poetry.lock should be version-controlled (i.e. tracked by Git) so that the next user can reproduce the exact environment based on the poetry.lock file.