1.10: Add position information to PointsCategories

[djdameln]

Duplicate of #1695, targeted to release branch instead of develop

Summary

This PR adds optional position information as meta-info for (key)point annotations. The position information can be used to define one or multiple default relative positions of a set of keypoints, for example a set of default human poses (standing, running etc) for human keypoint detection datasets. This type of meta-information about points data is useful in annotation tools.

Changes

• Adds positions attribute to PointsCategories.Category class. Similar to the Points annotation type, the positions are represented as a list of floats in the format [x1, y1, x2, y2, ..., xn, yn]. The positions are optional and default to an empty list.
• Adds a validator that validates the position coordinates that are passed to the Category constructor. Also validates if the number of position coordinates is the same as the number of labels.
• Adds a normalization function that normalizes the positions to the [0, 1] range (preserving aspect ratio). The normalization function is called by the validator to ensure that position information in the PointsCategories instance is always normalized.
• Adds logic to Datumaro format importer and exporter, to ensure that position information gets stored in the annotations json, and is also loaded correctly during import. The importer can handle datasets where position information is missing, so backward compatibility is preserved.
• Adds unit tests for normalization, validation and import/export functionality described above.

How to test

Add some position information to the PointsCategories instance of a keypoint detection dataset, then try export and importing the dataset.

Checklist

• I have added unit tests to cover my changes.​
• I have added integration tests to cover my changes.​
• I have added the description of my changes into CHANGELOG.​
• I have updated the documentation accordingly

License

• I submit my code changes under the same MIT License that covers the project.
  Feel free to contact the maintainers if that's a concern.
• I have updated the license header for each file (see an example below).

# Copyright (C) 2024 Intel Corporation
#
# SPDX-License-Identifier: MIT

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Please upload report for BASE (releases/1.10.0@811641f). Learn more about missing BASE report.

Additional details and impacted files

@@                Coverage Diff                 @@
##             releases/1.10.0    #1702   +/-   ##
==================================================
  Coverage                   ?   81.14%           
==================================================
  Files                      ?      284           
  Lines                      ?    32891           
  Branches                   ?     5299           
==================================================
  Hits                       ?    26688           
  Misses                     ?     4751           
  Partials                   ?     1452           

Flag	Coverage Δ
ubuntu-20.04_Python-3.10	81.12% <100.00%> (?)
windows-2022_Python-3.10	81.11% <100.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.