✨ Add Support for QuPath Annotation Imports

[measty]

This PR is intended to make importing objects from QuPath (and other applications) easier. I have updated it to follow the suggestion of John to do it via dependency injection.

If you export some objects in .geojson from some versions of QuPath, and they have measurements, all the measurements are in a 'measurements' property in the geojson. This means, when you import into annotation store, it will import fine but the properties dict will look something like:

properties = {a couple other props, "measurements": [{'name': 'propA', 'value': valA}, {'name': 'propB', 'value': valB}, etc]}

Which is awkward for many downstream things with the nested data structure, and doesn't really mesh with how annotations are intended to be represented in the store (usually a flat dict of properties unless there's a very good reason for nesting).

This PR adds an option to provide a transform to deal with any application-specific formatting, which for example can be used to unpack measurements when importing from QuPath to give instead in a properties dict with the measurement properties unpacked:

properties = {a couple other props, 'propA': valA, 'propB': valB, etc}

Importing from QuPath is probably one of the main use-cases for this, and an example is provided in the docstring for this case, but the additional flexibility means it can be used for other use-cases too.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (cca7443) 99.85% compared to head (dd16891) 99.85%.
Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #721   +/-   ##
========================================
  Coverage    99.85%   99.85%           
========================================
  Files           65       65           
  Lines         7517     7520    +3     
  Branches      1460     1461    +1     
========================================
+ Hits          7506     7509    +3     
  Misses           4        4           
  Partials         7        7           

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

[John-P]

An alternative approach would be to use dependency injection to achieve the same result. In this approach, you could provide a "transform" parameter (similar to PyTorch datasets) that accepts any callable and applies it to the annotation or properties during loading. The main advantage of this method is that it allows for different types of transformations to be applied during import, without the need to specify a separate set of keyword arguments for each transformation. also having many kwargs that could conflict may be annoying. You could even chain or compose transforms (much like image transforms). This can be particularly useful when importing from another application, where different types of transformations may be required. You could then show a 'recipe' (see itertools recipes) for QuPath in the examples docstring or even provide some named transform functiosn for common imports.

e.g.

def qupath_transform(properties: dict) -> dict:
    """An example QuPath transform."""
    measurements = properties.pop("measurements", {})
    properties.update(measurements)
    return properties

def another_app_transform(properties: dict) -> dict:
    """An example transform for annotation from another application."""
    ...

store.from_geojson("qupath_annotation.json", transform=qupath_transform)

This could alternatively be a transform that takes an annotation instead of just the properties dict e.g. if you wanted to apply a geometric transform based on the properties etc.

Not required of course, but I think it would make things easier to test and add greater flexibility.

[shaneahmed]

Please can you make the changes as suggested by @John-P and discussed during the meeting on Friday?

[shaneahmed]

Thanks @measty