Commit 658e03cf authored by Timm Schoening's avatar Timm Schoening
Browse files

Update README.md

parent 290504ef
# Introduction
Marine image data collections need a core set of standardized metadata for FAIR and open publication. An entire image set (e.g. deployment) requires header information on the ownership and allowed usage of the collection. Numerical metadata is required for each image on its acquisition position. It is recommended to provide further optional metadata.
Achieving FAIRness and Openness of (marine) image data requires structured and standardized metadata on the image data itself and the visual and semantic image data content. This metadata shall be provided in the form of FAIR digital object (FDOs). The following definitions describe how the image data itself shall be enriched by iFDOs, the visual content of the images by Proxy-FDOs (pFDOs) and the semantic content of the image data by sFDOs.
# Version
This is **Version 0.9.2** of the DataHub/MareHub working group "Videos / Images" metadata vocabulary and profile for marine imagery. It is referred to as: **MareHub_VideosImages_MVP_0.9.2**. It is the foundation for publishing and accessing marine image data according to the working group's standard operating procedure: **MareHub_VideosImages_SOP_0.9.2**.
Continuous versioning of the FDOs is given by the commit hashes. Releases with numerical versioning will be created upon major changes.
# Metadata vocabulary terms
The following wording will be used throughout the document.
The following wording will be used throughout the documents.
- images: photos (still images) and videos (moving images) acquired by cameras, recording the optical spectrum of light (http://purl.org/dc/dcmitype/Image)
- still image: A static visual representation (http://purl.org/dc/dcmitype/StillImage)
- moving image: A series of visual representations imparting an impression of motion when shown in succession (http://purl.org/dc/dcmitype/MovingImage)
- image set: a collection of at least one, but usually many, images (http://purl.org/dc/dcmitype/Collection)
- `<tag>`: represent placeholders for information (variables)
- `<tag>`: represent various placeholders for information (like variables)
- `<project>`: the project, expedition or cruise acronym
- `<event>`: part of a project, this refers to the station number in marine sciences
- `<sensor>`: a unique, human-readable identifier (or nickname) for the data acquisition device / camera
# Image set:
All image metadata shall be stored in one FAIR digital object (FDO) file. This file shall contain all header and detail fields for the image set. The file should be human and machine-readable, hence *.yaml format is recommended. The file name should be: <project>_<event>_<sensor>_iFDO.yaml
## Header information
All metadata fields can be part of the image-set block in case they are static (always the same value for each image). In case they do vary across the dataset, the metadata of each image may also contain this value, but without the "-set" term (e.g. image-acquisition-settings). The metadata for an image always supersedes the corresponding metadata for the image-set! Bold: suggested best-practice.
### Required
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| image-set-name | **`project>_<event>_<sensor>`** | A unique name for the image set |
| image-set-context | `<project>` | Project or expedition or cruise or experiment or ... |
| image-set-event | `<event>` | One event of a project or expedition or cruise or experiment or ... |
| image-set-platform | `<platform>` | Sensors URN or Equipment Git ID (Handle) |
| image-set-sensor | `<sensor>` | Sensors URN or Equipment Git ID (Handle) |
| image-set-uuid | UUID | A UUID (**version 4 - random**) for the entire image set |
| image-set-data-handle | Handle String | A Handle (using the UUID?) to point from the metadata to the data |
| image-set-metadata-handle | Handle String | A Handle (using the UUID?) to point to this metadata record |
| image-set-crs | **EPSG:4326**, ... | The coordinate reference system |
| image-set-type | String | Video, Photo, Microscopy, ... |
| image-set-creator | **Orcid** | Orcid (or Name, E-Mail) |
| image-set-license | CC-BY-NC / **CC-BY** / CC-0 | Copyright sentence / contact person or office |
| image-set-coordinate-uncertainty | Float [m] | Average/static uncertainty of coordinates in this dataset, given in meters |
### Optional (domain-specific)
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| image-set-event-information | Text | general information on the event (aka station, experiment), e.g. overlap between images/frames, parameters on platform movement, reference system used for scaling images like laser points |
| image-set-reference-calibration | Text | Calibration data and information on calibration process |
| image-set-time-synchronisation | Text | Synchronisation procedure and determined time offsets between camera recording values and UTC |
| image-set-item-identification-scheme | Text | How the images file names are constructed. Should be like this `<project>_<event>_<sensor>_<date>_<time>.<ext>` |
| image-set-curation-protocol | Text | A description of the image and metadata curation steps and results |
| image-set-acquisition-settings | **yaml**/json, free keys | Camera and lens settings (e.g. f number, acquisition time) |
| image-set-camera-intrinsics | **yaml**/json, free keys | focal lengths etc. |
| image-set-camera-extrinsics | **yaml**/json, free keys | x,y,z position offsets of the camera on the deployment frame and yaw, pitch, roll offsets of the camera mounting on the frame |
## Image information (Frequency: per image or per second of video):
### Required
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| image-uuid | UUID | UUID (**version 4 - random**) for the image file (still or moving) |
| image-filename | `<project>_<event>_<sensor>_<datetime>.[jpg,png,tif,raw,...]` | A filename string to identify the image data on disk (no absolute path!) |
| image-datetime | UTC: YYYY-MM-DD HH:MM:SS.SSSSS+0000 | |
| image-longitude | longitude [deg] | Decimal degrees: D.DDDDDDD |
| image-latitude | latitude [deg] | Decimal degrees: D.DDDDDDD |
| image-depth | Float [m] | Use when camera below water, then it has positive values |
| image-altitude | Float [m] | Use wenn camera above water, then it has positive values |
### Optional (domain-specific)
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| image-pixel-per-millimeter | Float [px/mm^2 = MPx/m^2] | Resolution of the imagery in pixels / millimeter which is identical to megapixel / square meter |
| image-meters-above-ground | Float [m] | Distance of the camera to the seafloor |
| image-coordinate-uncertainty | Float [m] | Optional, only needed when no static value is given for the image-set |
| image-acquisition-settings | **yaml**/json, free keys | Optional, only needed when no static value is given for the image-set |
| image-camera-intrinsics | **yaml**/json, free keys | Optional, only needed when no static value is given for the image-set |
| image-camera-extrinsics | **yaml**/json, free keys | Optional, only needed when no static value is given for the image-set |
# Example:
File name: SO268-1_021-1_GMR_CAM-23_iFDO.yaml:
```
image-set-name: SO268-1_21-1_GMR_CAM-23
image-set-context: SO268-1
image-set-event: 21-1
image-set-platform: SO_OFOS-1
image-set-sensor: GMR_CAM-23
image-set-uuid: 2a2360e9-a5ec-4ad2-be04-0ea0b4cbdc58
image-set-crs: EPSG:4326
image-set-type: photo
image-set-creator: Y. Bodur
image-set-license: CC-BY
image-set-coordinate-uncertainty: 13.42
image-set-event-information: Towed camera deployment to assess the health status of the eastern part of the Foobar reef.
image-set-reference-calibration: Checkerboard with 3cm box length imaged before deployment.
image-set-time-synchronisation: Camera set to UTC over RS232 before the deployment. No offset occured after post-deployment check.
image-set-item-identification-scheme: PROJECT_EVENT_SENSOR_DATETIME.jpg
image-set-curation-protocol: Navigation data smoothed and splined (see navigation sensor protocol for details), and assigned to imagery by timestamp. Coordinate uncertainty is given by standard deviation from navigation smoothing. Imagery without content (all black) due to lamp failure were removed manually.
image-set-acquisition-settings: Camera set to auto mode for ISO, f-number and exposure time
image-item-data:
SO268-1_21-1_GMR_CAM-23_20190513_131415.jpg:
image-uuid: 9999ba88-1a20-4efe-a0ac-6b4233490ad6
image-datetime: 2019-05-13 13:14:15+0000
image-longitude: -123.854637
image-latitude: 42.133426
image-depth: 4230.3
image-pixel-per-millimeter: 12.1
image-meters-above-ground: 1.3
image-coordinate-uncertainty: 4.2
SO268-1_21-1_GMR_CAM-23_20190513_131416.jpg:
image-uuid: 1c266c00-33e7-4e69-bc9a-f90fb1bce6d0
image-datetime: 2019-05-13 13:14:16+0000
image-longitude: -123.854638
image-latitude: 42.133427
image-depth: 4230.4
image-pixel-per-millimeter: 12.1
image-meters-above-ground: 1.4
SO268-1_21-1_GMR_CAM-23_20190513_131417.jpg:
...
alternative for videos:
SO268-1_21-1_GMR_CAM-23_20190513_111213.mp4:
image-uuid: 9999ba88-1a20-4efe-a0ac-6b4233490ad6
image-seconds:
0:
image-datetime: 2019-05-13 13:14:15+0000
image-longitude: -123.854637
image-latitude: 42.133426
image-depth: 4230.3
image-pixel-per-millimeter: 12.1
image-meters-above-ground: 1.3
image-coordinate-uncertainty: 4.2
1:
image-datetime: 2019-05-13 13:14:16+0000
image-longitude: -123.854638
image-latitude: 42.133427
image-depth: 4230.4
image-pixel-per-millimeter: 12.1
image-meters-above-ground: 1.4
SO268-1_21-1_GMR_CAM-23_20190513_131419.mp4:
image-uuid: 7cf53535-c80c-4eac-94d4-30fe4a521fd9
image-seconds:
0: ...
```
An example is available in the file: SO268-1_021-1_GMR_CAM-23_example-iFDO.yaml
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment