Contents

• Overview
• Installation
• Usage
• Documentation
• Contributing
• License
• Contact
• Citation
• Acknowledgments

Overview

ifdo-py is a Python library for working with iFDO (image FAIR Digital Object) files, the metadata standard for FAIR marine imagery. It provides a fully typed Pydantic data model covering the iFDO core, capture, and content sections, with validation, controlled-vocabulary enumerations, and round-trip serialization between Python objects and iFDO YAML or JSON files.

The library currently implements iFDO v2.2.1 and is developed collaboratively by CSIRO, MBARI and AWI. It serves as the iFDO layer for the Marimba framework for structuring, processing, packaging and distributing FAIR scientific image datasets.

(back to top)

Installation

pip install ifdo

Requires Python 3.10 or newer.

(back to top)

Usage

Read and write iFDO files

from ifdo import iFDO

# Read from a YAML or JSON file (.yaml, .yml, or .json)
ifdo_object = iFDO.load("ifdo.yaml")

# Write back out in either format
ifdo_object.save("ifdo.json")

Create an iFDO from scratch

from datetime import datetime, timezone

from ifdo import iFDO
from ifdo.models import (
    ImageAcquisition,
    ImageContext,
    ImageCreator,
    ImageData,
    ImageIllumination,
    ImageLicense,
    ImageMarineZone,
    ImagePI,
    ImageSetHeader,
)

header = ImageSetHeader(
    image_set_name="SO268-1_21-1_OFOS",
    image_set_uuid="f840644a-fe4a-46a7-9791-e32c211bcbf5",
    image_set_handle="https://hdl.handle.net/20.500.12085/f840644a-fe4a-46a7-9791-e32c211bcbf5",
    image_context=ImageContext(name="SO268 cruise"),
    image_pi=ImagePI(name="Jane Doe", uri="https://orcid.org/0000-0000-0000-0000"),
    image_creators=[ImageCreator(name="Jane Doe")],
    image_license=ImageLicense(name="CC BY 4.0", uri="https://creativecommons.org/licenses/by/4.0/"),
)

image = ImageData(
    image_datetime=datetime(2019, 3, 4, 8, 37, 24, tzinfo=timezone.utc),
    image_latitude=-42.123,
    image_longitude=145.456,
    image_altitude_meters=-4130.5,
    image_acquisition=ImageAcquisition.PHOTO,
    image_illumination=ImageIllumination.ARTIFICIAL_LIGHT,
    image_marine_zone=ImageMarineZone.SEAFLOOR,
)

ifdo_object = iFDO(image_set_header=header, image_set_items={"image_0001.jpg": image})
ifdo_object.save("ifdo.yaml")

Field names are written in the iFDO kebab-case convention, and the output declares the iFDO version and schema it conforms to:

image-set-header:
  image-context:
    name: SO268 cruise
  image-pi:
    name: Jane Doe
    uri: https://orcid.org/0000-0000-0000-0000
  image-creators:
  - name: Jane Doe
  image-license:
    name: CC BY 4.0
    uri: https://creativecommons.org/licenses/by/4.0/
  image-set-name: SO268-1_21-1_OFOS
  image-set-uuid: f840644a-fe4a-46a7-9791-e32c211bcbf5
  image-set-handle: https://hdl.handle.net/20.500.12085/f840644a-fe4a-46a7-9791-e32c211bcbf5
  image-set-ifdo-version: v2.2.1
image-set-items:
  image_0001.jpg:
    image-acquisition: photo
    image-illumination: artificial light
    image-marine-zone: seafloor
    image-datetime: '2019-03-04 08:37:24.000000'
    image-latitude: -42.123
    image-longitude: 145.456
    image-altitude-meters: -4130.5
$schema: http://hdl.handle.net/20.500.12085/22aba7d7-c432-49ab-bebe-ee8ed4f70150

Videos are supported by assigning a list of ImageData objects to an item, one entry per point in time, as specified by the iFDO standard.

Create image annotations

from datetime import datetime, timezone

from ifdo.models import AnnotationLabel, ImageAnnotation, ImageData

# Create a label
label = AnnotationLabel(
    label="fish",
    annotator="Jane Doe",
    created_at=datetime(2026, 6, 10, tzinfo=timezone.utc),
    confidence=0.9,
)

# Pack it into a rectangle annotation with a flat list of x/y coordinates
annotation = ImageAnnotation(
    coordinates=[0.0, 0.0, 1.0, 0.0, 1.0, 1.0, 0.0, 1.0],
    labels=[label],
    shape="rectangle",
)

image = ImageData(image_annotations=[annotation])

Validation

All models are Pydantic models, so values are validated at construction time: latitudes and longitudes are range-checked, controlled-vocabulary fields only accept their iFDO enumeration values, and structural constraints from the iFDO schema (such as the 9-element stereo rotation matrix or the at-least-one-entry rule for image-creators) are enforced before anything is written to disk.

from ifdo.models import ImageData

ImageData(image_latitude=120.0)  # raises pydantic.ValidationError: latitude must be <= 90

(back to top)

Documentation

• iFDO standard documentation including the field reference and changelog
• FAIR marine images overview
• Marimba, a framework that uses ifdo-py to produce FAIR image datasets

(back to top)

Contributing

Contributions are welcome! Please see the Contributing Guide for details on the development workflow, code standards, and pull request process.

(back to top)

License

This project is licensed under the MIT License.

(back to top)

Contact

• Chris Jackett - CSIRO - chris.jackett@csiro.au
• Kevin Barnard - MBARI - kbarnard@mbari.org
• Karsten Schimpf - AWI - karsten.schimpf@awi.de

(back to top)

Citation

If you use ifdo-py in your work, please cite the iFDO standard:

Schoening, T., Durden, J. M., Faber, C., Felden, J., Heger, K., Hoving, H. J. T., Kiko, R., Köser, K., Krämmer, C., Kwasnitschka, T., Möller, K. O., Nakath, D., Naß, A., Nattkemper, T. W., Purser, A., & Zurowietz, M. (2022). Making marine image data FAIR. Scientific Data, 9, 414. https://doi.org/10.1038/s41597-022-01491-3

@article{schoening2022ifdo,
  title={Making marine image data FAIR},
  author={Schoening, Timm and Durden, Jennifer M and Faber, Claas and Felden, Janine and Heger, Karl and Hoving, Henk-Jan T and Kiko, Rainer and K{\"o}ser, Kevin and Kr{\"a}mmer, Christiane and Kwasnitschka, Tom and M{\"o}ller, Klas Ove and Nakath, David and Na{\ss}, Andrea and Nattkemper, Tim W and Purser, Autun and Zurowietz, Martin},
  journal={Scientific Data},
  volume={9},
  pages={414},
  year={2022},
  publisher={Nature Publishing Group},
  doi={10.1038/s41597-022-01491-3}
}

A citation file for the ifdo-py software itself is available via the "Cite this repository" button on GitHub.

(back to top)

Acknowledgments

ifdo-py is developed collaboratively by CSIRO (Commonwealth Scientific and Industrial Research Organisation, Australia), MBARI (Monterey Bay Aquarium Research Institute, USA) and AWI (Alfred Wegener Institute, Germany). The iFDO standard is developed by the Marine Imaging community.

(back to top)