Add position information to PointsCategories

[djdameln]

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 ✅

Project coverage is 81.21%. Comparing base (da9e481) to head (00cd481).
Report is 23 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1695      +/-   ##
===========================================
+ Coverage    81.19%   81.21%   +0.01%     
===========================================
  Files          283      284       +1     
  Lines        33005    33035      +30     
  Branches      5309     5313       +4     
===========================================
+ Hits         26798    26828      +30     
  Misses        4753     4753              
  Partials      1454     1454              

Flag	Coverage Δ
ubuntu-20.04_Python-3.10	81.19% <100.00%> (+0.01%)	⬆️
windows-2022_Python-3.10	81.18% <100.00%> (+0.01%)	⬆️

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.

[A-Artemis]

What is attribute referring to here?
Could you please add the params and return to the doc string, and type hinting please.

[djdameln]

attribute is a mandatory argument for this validator method, that gets passed to the method internally by the attr library. It contains some meta information about the to be validated attribute (in this case positions), such as name, expected type and default value. I added type annotations and some refactoring to make it more clear.