iFDO core#
The iFDO core is one section of the complete iFDO file. See its description to learn about its file formats, parts and sections.
Header information in the image-set-header part#
The image-set-header values have to exist and cannot be superseded by values of the image-set-items.
Fields from the image-set-items part (below) may exist in the header as default values for the entire image set.
| Field | Type | Description |
|---|---|---|
| image-set-name | string | A unique name for the image set, should include image-project, image-event, image-sensor and optionally the purpose of imaging |
| image-set-uuid | string | A random UUID assigned to the entire image set |
| image-set-handle | string | A Handle URL (suggested: using the image-set-uuid) to point to the landing page of the data set |
| image-set-ifdo-version | string | The semantic version information of the iFDO standard used. |
| image-datetime | string | Full UTC datetime of image acquisition (or start time of a video) as in ISO8601. The default format here is ‘YYYY-MM-DD hh:mm:ss.sss’ with a space between date and time as in ISO 8601:2004. Other formats may be used if defined in the field ‘image-datetime-format’. |
| image-handle | string | The URI pointing to a downloadable version of the image data |
| image-latitude | number | Y-coordinate of the camera center in decimal degrees: D.DDDDDDD (use at least seven significant digits that is ca. 1cm resolution on Earth) |
| image-longitude | number | X-coordinate of the camera center in decimal degrees: D.DDDDDDD (use at least seven significant digits that is ca. 1cm resolution on Earth) |
| image-altitude-meters | number | Z-coordinate of camera center in meters. Has negative values when camera is below sea level. Has positive values when the camera is above sea level. |
| image-coordinate-reference-system | string | The coordinate reference system, e.g. EPSG:4326 |
| image-coordinate-uncertainty-meters | number | The average/static uncertainty of coordinates in this dataset, given in meters. Computed e.g. as the standard deviation of coordinate corrections during smoothing / splining. |
| image-context | object | The overarching project context within which the image set was created |
| image-project | object | The more specific project or expedition or cruise or experiment or … within which the image set was created. |
| image-event | object | One event of a project or expedition or cruise or experiment or … that led to the creation of this image set. |
| image-platform | object | A URI pointing to a description of the camera platform used to create this image set |
| image-sensor | object | A URI pointing to a description of the sensor used to create this image set. |
| image-uuid | string | A (random) UUID for the individual image file (still or moving). This UUID needs to be embedded within the image files. For still images in the exif tag ‘ImageUniqueID’, for videos in the XMP tag ‘identifier’ in the Dublin Core namespace. For Matroska video containers the first ‘Segment UID’ is used. |
| image-hash-sha256 | string | An SHA256 hash to represent the whole file (including UUID in file metadata header!) to verify integrity on disk |
| image-pi | object | Information to identify the principal investigator |
| image-creators | array | A list containing dicts for all creators containing: |
| image-license | object | A URL pointing to the license to use the data (should be FAIR, e.g. CC-BY or CC-0) |
| image-copyright | string | Copyright statement or contact person or office |
| image-abstract | string | 500 - 2000 characters describing what, when, where, why and how the data was collected. Includes general information on the event (aka station, experiment), e.g. overlap between images/frames, parameters on platform movement, aims, purpose of image capture etc. |
| image-set-local-path | string | Local relative or absolute path to a directory in which (also its sub-directories), the referenced image files are located. Absolute paths must start with and relative paths without path separator (ignoring drive letters on windows). The default is the relative path ../raw. |
In JSON, the entire image-set-header part is one dictionary.
Image item information#
| Field | Type | Description |
|---|---|---|
| image-set-name | string | A unique name for the image set, should include image-project, image-event, image-sensor and optionally the purpose of imaging |
| image-set-uuid | string | A random UUID assigned to the entire image set |
| image-set-handle | string | A Handle URL (suggested: using the image-set-uuid) to point to the landing page of the data set |
| image-set-ifdo-version | string | The semantic version information of the iFDO standard used. |
| image-datetime | string | Full UTC datetime of image acquisition (or start time of a video) as in ISO8601. The default format here is ‘YYYY-MM-DD hh:mm:ss.sss’ with a space between date and time as in ISO 8601:2004. Other formats may be used if defined in the field ‘image-datetime-format’. |
| image-handle | string | The URI pointing to a downloadable version of the image data |
| image-latitude | number | Y-coordinate of the camera center in decimal degrees: D.DDDDDDD (use at least seven significant digits that is ca. 1cm resolution on Earth) |
| image-longitude | number | X-coordinate of the camera center in decimal degrees: D.DDDDDDD (use at least seven significant digits that is ca. 1cm resolution on Earth) |
| image-altitude-meters | number | Z-coordinate of camera center in meters. Has negative values when camera is below sea level. Has positive values when the camera is above sea level. |
| image-coordinate-reference-system | string | The coordinate reference system, e.g. EPSG:4326 |
| image-coordinate-uncertainty-meters | number | The average/static uncertainty of coordinates in this dataset, given in meters. Computed e.g. as the standard deviation of coordinate corrections during smoothing / splining. |
| image-context | object | The overarching project context within which the image set was created |
| image-project | object | The more specific project or expedition or cruise or experiment or … within which the image set was created. |
| image-event | object | One event of a project or expedition or cruise or experiment or … that led to the creation of this image set. |
| image-platform | object | A URI pointing to a description of the camera platform used to create this image set |
| image-sensor | object | A URI pointing to a description of the sensor used to create this image set. |
| image-uuid | string | A (random) UUID for the individual image file (still or moving). This UUID needs to be embedded within the image files. For still images in the exif tag ‘ImageUniqueID’, for videos in the XMP tag ‘identifier’ in the Dublin Core namespace. For Matroska video containers the first ‘Segment UID’ is used. |
| image-hash-sha256 | string | An SHA256 hash to represent the whole file (including UUID in file metadata header!) to verify integrity on disk |
| image-pi | object | Information to identify the principal investigator |
| image-creators | array | A list containing dicts for all creators containing: |
| image-license | object | A URL pointing to the license to use the data (should be FAIR, e.g. CC-BY or CC-0) |
| image-copyright | string | Copyright statement or contact person or office |
| image-abstract | string | 500 - 2000 characters describing what, when, where, why and how the data was collected. Includes general information on the event (aka station, experiment), e.g. overlap between images/frames, parameters on platform movement, aims, purpose of image capture etc. |
| image-set-local-path | string | Local relative or absolute path to a directory in which (also its sub-directories), the referenced image files are located. Absolute paths must start with and relative paths without path separator (ignoring drive letters on windows). The default is the relative path ../raw. |
In JSON, the image-set-items part is one dictionary. The keys in that dictionary are the filenames of the items in
the image set. Each item, indexed by the image-filename, is itself either a dictionary if the item is an image or a list of dictionaries if the item is a video.
For videos, the first entry of the list contains the default fields for the entire video. Subsequent entries allow to add time-dependent metadata. Do not repeat static metadata for each second of
a video to avoid repetition. Every subsequent entry contains specifications that supersede the default values for
one specific time point of the video. For photos (still images) the dictionary contains the fields
tabled above.
UUIDs and hashes#
UUID#
Making data FAIR requires - amongst other things - that data is assigned a persistent identifier (PID). Many such PID systems exist, and usually they are based on the handle system (like DOIs for example) and alpha-numerical IDs that are globally unique. For images, we chose to use UUIDs (Universally Unique Identifiers), more precisely UUID type 4: random. These UUIDs can be created by anyone and as there are ca 21^36 possible UUID4s making it almost impossible that the same one is created more than once. This UUID is the alphanumerical identifier that has to be assigned to each image and to each image set. That means that the UUID for an image item (a photo or video) has to become part of the file itself! You need to write it into the image file’s metadata header. How this can be done depends on the image file format you chose but in general the two magnificent software tools exiftool anf ffmpeg are the solution. In case you are using the MarIQT software, these tools are used under the hood.
Hash#
We use hashes to document the integrity of the image files. A hash is like a fingerprint of the file as it is computed from the file’s byte content. If you like, it is a massive compression of the file’s data into a short, cryptic text (ca. 32 characters) but unlike a zip file there is no way to uncompress the file from the hash. Using hashes allows us to make sure that a file has not gone corrupt or that a particular file is actually the version we are interested in. Checking the integrity of a file with hashes requires, that the byte content does not change. It is therefore absolutely essential, that the UUID is written to the image file’s metadata header before the hash for that file is computed!