Design Decisions

Concrete Dependencies and Updating

This package, like many others, has dependencies that need to be fulfilled for proper functionality to be satisfied. While these general requirements, found in the pyproject.toml file, are known as “abstract” requirements, we also choose to codify “concrete” requirements here via the poetry.lock file. This distinction is described well by [Stufft], using the setuptools-based resources which are parallel in use to the above respectively described files.

While xaitk-saliency is a library, we choose to retain concrete dependencies via the poetry.lock file in order to maintain consistency of environment across developers as well as CI processes. This falls in conceptual line with the “Developing Reusable Things or How Not to Repeat Yourself” section from [Stufft]. However, we are still a “library” and desire to make sure that we work with the “latest” versions of our listed abstract dependencies (within some reasonable time window). Currently, such concrete “version bumps” happen in the form of periodic update branches that update the poetry.lock file via a poetry update call. These updates are submitted as PRs to the upstream repository and allow the standard suite of CI checks to be performed to make sure the updated versions do not break anything. The timing of such updates are currently not concretely scheduled, nor are they specifically tied to events, but more on an “every so often” cadence that is relatively more frequent than versioned releases.

Image format

We choose to use the numpy.ndarray data structure for our image representation in this toolkit. Earlier, we utilized the Pillow package’s PIL.Image.Image data-structure but encountered issues in certain use-cases regarding large images, images with non-standard quantities of channels (e.g. > 3) or with imagery consisting of 12 or 16-bit valuation. Additionally, other popular and highly utilized packages in the python community, like OpenCV, Scikit-Image and PyTorch to name a few, utilize raw numpy.ndarray matrices as the container for image data.