h5-info-pkg-inra-phenome 1.3.4
Utility package for extracting, reading and saving metadata from HDF5 Phenomobile V2, Phenoverger and LITERAL acquisition files
Requires Python: >=3.8

# H5Info Package

This Python package contains the necessary tools to extract data and metadata from HDF5 files generated by Phenomobile or PhenoMan (LITERAL) acquisition in the context of the Phenome project by INRAE, France.

The API of the H5Info package exposes 3 methods:

- ``load_data()``: to extract data from a HDF5 file and store it into a ``H5Info`` Python structure
- ``save_metadata()``: to save a ``H5Info`` metadata structure into a JSON  file
- ``load_metadata()``: to load a ``H5Info`` metadata structure from a JSON file

If an error occurs because of invalid data, a ``DataError`` exception is raised. A good practice consists in catching this error in a separate ``except`` block than the other exceptions.

Please refer to the ``main.py`` script for an example about how to use these three methods.

## Install H5Info module

The H5Info module is deployed on PyPi (Python Package Index) under the name [h5-info-pkg-inra-phenome](https://pypi.org/project/h5-info-pkg-inra-phenome/).

To install the H5Info module on your local environment, run the following command by indicating the specific version needed (here 1.3.0):

``pip install h5-info-pkg-inra-phenome==1.3.0``

## H5Info Structure Example

``h5_info = H5Info()``

### Session

- ``h5_info.session.date = 2020-02-03_09:45:23``
- ``h5_info.session.experiment_id = "2019_SunRise"``
- ``h5_info.session.experiment_uri = "http://www.phenome-fppn.fr/diaphen/2019/v1901"``
- ``h5_info.session.local_infra = "Diaphen"``
- ``h5_info.session.national_infra = "PHENOME"``

### Plot

- ``h5_info.plot.id = "20LP4_129_8_1039"``
- ``h5_info.plot.uri = "http://www.phenome-fppn.fr/diaphen/2018/v1801"``
- ``h5_info.plot.coordinates = [[1.5015271931087, 43.532682695713], [1.5015062032854, 43.532676540606], [1.5014877113578, 43.532709920144], [1.5015087011914, 43.532716075254]]``
- ``h5_info.plot.orientation = 158.04785481961858``

### Vector

- ``h5_info.vector.id = "Phenomobile V2"``
- ``h5_info.vector.uri = "http://www.phenome-fppn.fr/diaphen/2018/v1801"``
- ``h5_info.vector.serial_nb = "PHENOMOBILE_V2_02"``
- ``h5_info.vector.acquisition_version = "2.0"``
- ``h5_info.vector.format_version = "1.8"``

### Sensors

``for sensor in h5_info.sensors:``

- ``sensor.id = "4"``
- ``sensor.type = "camera"``
- ``sensor.description = "camera_1"``
- ``sensor.manufacturer = "Baumer"``
- ``sensor.firmware = "1.2.0"``
- ``sensor.model = "VLG 40C"``
- ``sensor.serial_nb = "00_06_be_01_62_f0"``
- ``sensor.uri = "http://www.phenome-fppn.fr/agrophen/2019/s19003"``

``if sensor.type == TYPE_CAMERA:``

- ``sensor.bayer_grid = "Bayer_RG12"``
- ``sensor.focal_length = 25.0``
- ``sensor.lens_angular_aperture = 28.0``

Notice that if these optional fields are not available they are initialized to 0.0 or empty string. Therefore, it is possible to determine whether to use a default value by doing the following, for example:

```python
if not sensor.focal_length:
    sensor.focal_length = 25.0
```

### Image

``for image in sensor.images:``

- ``image.name = "camera_1_1"``
- ``image.date = 2019-06-04_12:11:52.316072``

Camera, Multispectral and Lidar images have also their own specific attributes.

``CameraImage`` attributes:

- ``image.shutter_time = 500``
- ``image.width = 2040``
- ``image.height = 2044``
- ``image.size = 8339520``

``LidarImage`` attributes:

- ``image.frequency = 300.0``
- ``image.angle_increment = 0.003490658476948738``

``MultispectralCameraImage`` attributes:

- ``image.size = 2461422``
- ``image.channel = 450``

### Position

Each sensor also has its own set of positions :

- ``sensor.position.pitch = "0.0"``
- ``sensor.position.roll = "-180.0"``
- ``sensor.position.yaw = "-90.0"``
- ``sensor.position.x = "0.02"``
- ``sensor.position.y = "0.23"``
- ``sensor.position.z = "0.0"``

### Others fields

The ``H5Info`` structure contains other fields not detailed here, such as ``static transforms`` factors describing the positions (x, y, z, pitch, rool and yaw) of each element composing the acquisition system.

In addition, a geolocalisation file containing positions of the head is saved in a separate file named `*-geo.csv``