README.md 9.28 KB
Newer Older
Timm Schoening's avatar
Timm Schoening committed
1
2
# 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. 
Timm Schoening's avatar
Timm Schoening committed
3

Timm Schoening's avatar
Timm Schoening committed
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 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**.

# Metadata vocabulary terms
The following wording will be used throughout the document.
- 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)
- `<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
Timm Schoening's avatar
Timm Schoening committed
22
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.
Timm Schoening's avatar
Timm Schoening committed
23

Timm Schoening's avatar
Timm Schoening committed
24
### Required
Timm Schoening's avatar
Timm Schoening committed
25
26
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
Timm Schoening's avatar
Timm Schoening committed
27
28
29
30
31
32
| 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 |
Timm Schoening's avatar
Timm Schoening committed
33
34
| 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 |
Timm Schoening's avatar
Timm Schoening committed
35
| image-set-crs | **EPSG:4326**, ... | The coordinate reference system |
Timm Schoening's avatar
Timm Schoening committed
36
| image-set-type | String | Video, Photo, Microscopy, ... |
Timm Schoening's avatar
Timm Schoening committed
37
38
| 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 |
Timm Schoening's avatar
Timm Schoening committed
39
| image-set-coordinate-uncertainty | Float [m] | Average/static uncertainty of coordinates in this dataset, given in meters |
Timm Schoening's avatar
Timm Schoening committed
40

Timm Schoening's avatar
Timm Schoening committed
41
42
43
44
45
46
47
48
49
50
51
### 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 |
Timm Schoening's avatar
Timm Schoening committed
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

## 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:
Timm Schoening's avatar
Timm Schoening committed
78
```
Timm Schoening's avatar
Timm Schoening committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
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: ...
Timm Schoening's avatar
Timm Schoening committed
140
```