Commit 63851e06 authored by Timm Schoening's avatar Timm Schoening
Browse files

Update MareHub_AGVI_pFDO.md

parent d10a1e1c
# iFDO capture section
Information on how image data was captured is can be crucial to understand information extracted from the images. It is thus highly recommended to enrich all iFDOs with capture information. Some capture metadata are specified here for the purpose of visualizing the content of imagery in the MareHub data portal and in other contexts. The potential metadata in the iFDO capture section is expected to grow with time, as additional (marine) imaging domains make use of this concept. Anyhow, below you find a pool of iFDO capture fields which are highly recommened to be added to your iFDO. Only with these fields set will your dataset shine in the marine data portal!
## File format
All iFDO capture fields shall be stored alongside the core metadata in your iFDO file! It does not take up a specific section of the file, rather the values are intermixed into the image-set-header and image-set-items section!
# Recommended iFDO content fields (essential to be part of the marine data portal!)
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| image-set-acquisition | photo, video, scan | photo: still images, video: moving images, scan: microscopy / slide scans |
| image-set-quality | raw, processed, product | raw: straight from the sensor, processed: QA/QC'd, product: image data ready for interpretation |
| image-set-deployment | mapping, stationary, survey, exploration, experiment, sampling | mapping: planned path execution along 2-3 spatial axes, stationary: fixed spatial position, survey: planned path execution along free path, exploration: unplanned path execution, experiment: observation of manipulated environment, sampling: ex-situ imaging of samples taken by other method |
| image-set-navigation | satellite, beacon, transponder, reconstructed | satellite: GPS/Galileo etc., beacon: USBL etc., transponder: LBL etc., reconstructed: position estimated from other measures like cable length and course over ground |
| image-set-scale-reference | 3D camera, calibrated camera, laser marker, optical flow | 3D camera: the imaging system provides scale directly, calibrated camera: image data and additional external data like object distance provide scale together, laser marker: scale information is embedded in the visual data, optical flow: scale is computed from the relative movement of the images and the camera navigation data |
| image-set-illumination | sunlight, artificial light, mixed light | sunlight: the scene is only illuminated by the sun, artificial light: the scene is only illuminated by artificial light, mixed light: both sunlight and artificial light illuminate the scene |
| image-set-resolution | km, hm, dam, m, cm, mm, µm | average size of one pixel of an image |
| image-set-marine-zone | seafloor, water column, sea surface, atmosphere, laboratory | seafloor: images taken in/on/right above the seafloor, water column: images taken in the free water without the seafloor or the sea surface in sight, sea surface: images taken right below the sea surface, atmosphere: images taken outside of the water, laboratory: images taken ex-situ |
| image-set-spectral-resolution | grayscale, rgb, multi-spectral, hyper-spectral | grayscale: single channel imagery, rgb: three channel imagery, multi-spectral: 4-10 channel imagery, hyper-spectral: 10+ channel imagery |
| 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 |
# Further domain-specific or otherwise valuable iFDO capture fields
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| 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 |
| ... and many more to come | | Please suggest more! |
# Example
- [iFDO capture example](https://gitlab.hzdr.de/datahub/marehub/ag-videosimages/metadata-vocabulary-profile/-/blob/master/SO268-1_021-1_GMR_CAM-23_example-pFDO.yaml): SO268-1_021-1_GMR_CAM-23_example-iFDO_capture.yaml
- [iFDO capture vocabulary](https://gitlab.hzdr.de/datahub/marehub/ag-videosimages/metadata-profiles-fdos/-/blob/master/MareHub_AGVI_iFDO_capture-vocabulary.yaml): the set of allowed terms to be used in the set of recommended iFDO capture fields
# pFDO - proxy FAIR Digital Object
Image data is inherently unstructured and obtaining a glimpse of its content is hard to achieve for humans as well as machines. pFDOs are a mechanism to encode the content of image data by means of proxies. These can take various forms as described below. Simple examples are thumbnails for images or the average intensity along a video. Some proxies are specified here for the purpose of visualizing the content of imagery in the MareHub data portal and in other context. This collection of proxies is expected to grow with time, as additional (marine) imaging domains make use of this concept.
## File format
All proxy metadata shall be stored in one proxy FAIR digital object (pFDO) file. The file should be human and machine-readable, hence *.yaml format is recommended. The file name should be: `<project>_<event>_<sensor`_pFDO.yaml. Bold: suggested best-practice.
# Types of pFDO proxies
- pFDO core proxy **(Required)**: a set of 9 structured values (see table below from acquisition to spectral-resolution) required to specify the type of image set
- Entropy (Optional): a 1D time series constructed of single entropy values for each image / frame
- Particle count (Optional): a 1D time series constructed of single particle/object count values for each image / frame
- Average color (Optional): a set of `n` 1D time series constructed of the average colour for each image / frame and the `n` channels of an image (e.g. 3 for RGB)
- Sequence Image (Optional): a 2D image with the pixel dimension of `<number of images / frames> x <height of one image / frame>` containing one column of each image /frame in the image set, stacked along the horizontal of the sequence image according to the acquisition time.
- MPEG7 feature vectors (Optional): a group of nD feature vectors per image / frame of varying dimensionality according to the chosen MPEG7 descriptors.
# pFDO Fields
## Required pFDO fields:
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| image-set-name | Needs to include `<project>, <event>, <sensor>` and purpose | A unique name for the image set this pFDO belongs to (same as in the iFDO!) |
| image-set-uuid | UUID | The UUID (**version 4 - random**) for the entire image set this pFDO belongs to (same as in the iFDO!) |
| image-set-metadata-handle | Handle String | A Handle (using the UUID?) to point to the metadata record of the image set this pFDO belongs to (same as in the iFDO!) |
| image-set-creators | **Orcids** | Orcids (or Names, E-Mails) of the creators of the image set this pFDO belongs to (same as in the iFDO!) |
| pfdo-license | **CC-0** / CC-BY | Usage license of this pFDO. Should be CC-0. |
| pfdo-proxy-core | **yaml** | a well-defined set of categories (see below) with well-defined options. |
| pfdo-proxy-core:acquisition | photo, video, scan | photo: still images, video: moving images, scan: microscopy / slide scans |
| pfdo-proxy-core:image-quality | raw, processed, product | raw: straight from the sensor, processed: QA/QC'd, product: image data ready for interpretation |
| pfdo-proxy-core:deployment | mapping, stationary, survey, exploration, experiment, sampling | mapping: planned path execution along 2-3 spatial axes, stationary: fixed spatial position, survey: planned path execution along free path, exploration: unplanned path execution, experiment: observation of manipulated environment, sampling: ex-situ imaging of samples taken by other method |
| pfdo-proxy-core:navigation | satellite, beacon, transponder, reconstructed | satellite: GPS/Galileo etc., beacon: USBL etc., transponder: LBL etc., reconstructed: position estimated from other measures like cable length and course over ground |
| pfdo-proxy-core:scale-reference | 3D camera, calibrated camera, laser marker, optical flow | 3D camera: the imaging system provides scale directly, calibrated camera: image data and additional external data like object distance provide scale together, laser marker: scale information is embedded in the visual data, optical flow: scale is computed from the relative movement of the images and the camera navigation data |
| pfdo-proxy-core:illumination | sunlight, artificial light, mixed light | sunlight: the scene is only illuminated by the sun, artificial light: the scene is only illuminated by artificial light, mixed light: both sunlight and artificial light illuminate the scene |
| pfdo-proxy-core:resolution | km, hm, dam, m, cm, mm, µm | average size of one pixel of an image |
| pfdo-proxy-core:zone | seafloor, water column, sea surface, atmosphere, laboratory | seafloor: images taken in/on/right above the seafloor, water column: images taken in the free water without the seafloor or the sea surface in sight, sea surface: images taken right below the sea surface, atmosphere: images taken outside of the water, laboratory: images taken ex-situ |
| pfdo-proxy-core:spectral-resolution | grayscale, rgb, multi-spectral, hyper-spectral | grayscale: single channel imagery, rgb: three channel imagery, multi-spectral: 4-10 channel imagery, hyper-spectral: 10+ channel imagery |
## Optional pFDO fields (depending on imaging domain and pFDO types used)
| Field | Format / Values / Unit | Comment |
| ----- | ---------------------- | ------- |
| pfdo-proxy-entropy | **yaml** | `<image filename 1>: <entropy 1>\n<image filename 2>: <entropy 2\n...>` |
| pfdo-proxy-particle-count | **yaml** | `<image filename 1>: <particle count 1>\n<image filename 2>: <particle count 2\n...>` |
| pfdo-proxy-average-color | **yaml** | `<image filename 1>:\n\t<channel 0>: <value>\n\t<channel 1>: <value>\n<image filename 2>:\n\t<channel 0>: <value>\n...>` |
| pfdo-proxy-sequence-image | Handle | Handle URL to an image |
| pfdo-proxy-mpeg7-features | **yaml** | `<image filename 1>:\n\t<descriptor 0>: [<value>,<value>,...]\n\t<descriptor 1>: [<value>,<value>,...]\n<image filename 2>:\n\t<descriptor 0>: [<value>,<value>,...]\n...>` |
# Example
- [pFDO example](https://gitlab.hzdr.de/datahub/marehub/ag-videosimages/metadata-vocabulary-profile/-/blob/master/SO268-1_021-1_GMR_CAM-23_example-pFDO.yaml): SO268-1_021-1_GMR_CAM-23_example-pFDO.yaml
- [pFDO core proxy vocabulary](https://gitlab.hzdr.de/datahub/marehub/ag-videosimages/metadata-profiles-fdos/-/blob/master/MareHub_AGVI_pFDO_core-proxy-vocabulary.yaml): the set of allowed terms to be used in creating core proxies for pFDOs.
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