Generalizing Annotators

[philippjfr]

Early on in the development of the EarthSim library I developed the abstraction of an Annotator class. An Annotator as currently implemented provides a convenient way of using the point and polygon/path drawing tools on top of a map and then assign each point or polygon/path or even each vertex of polygon/path one or more values in a linked table. The idea was always that these annotators could be generalized in some way to allow them to be moved to a different library. Before outlining some different options for "generalizing" them I will list the obstacles to generalization.

1. They are tied to geographic usecases
   • They include tile sources because it is hard to add those after the fact
   • They must necessarily include projections if they are to be displayed on top of tile sources
   • To display coordinates in tables the callbacks must project Mercator -> lat/lon
2. Their logic is closely tied to the type of annotations, i.e. point/path/polygon
   • Each type of annotation requires different handling and supports different annotations, e.g. polygon vertices can be labelled but boxes/points only support single values
   • Different types of annotations require different drawing tools, e.g. poly/path annotations require both PolyDraw and VertexEdit tools while points only require PointDraw tool

Proposals for generalization

Better compositionality

Addresses limitation: 2

Currently there is a GeoAnnotator baseclass, then PointAnnotator and PolyAnnotator subclasses and finally a combined PolyAndPointAnnotator class forming a diamond shaped inheritance structure. This is problematic because if we wanted to add a new type of annotation (e.g. box) we'd now have a combinatorial explosion of subclasses (PolyAndBoxAnnotator, PolyAndBoxAndPointAnnotator etc.).

Instead of using subclassing to achieve this we should factor out an AnnotationManager and make that accept a list of Annotators, which would handle a particular type of annotation, e.g. point, poly/path, box etc. Each annotator would return two things:

• The list of layers to overlay on the drawing region
• The list of linked tables

The manager would compose these components into a panel. The manager would additionally support additional layers which allows declaring elements to overlay (or underlay) on the drawing region, which may be used for tile sources.

Pseudo-code declaration:

AnnotationManager(
    annotations=[PointAnnotator(), BoxAnnotator(), PolyAnnotator()],
    extra_layers={0: gv.tiles.OSM()}
)

Geo-independence

The problem of making this manager/annotator proposal independent of the geo-context is more difficult, each Annotator class would have to be subclassed to make it geo-aware. Depending on where we decide these components should live it may therefore be simpler to start by making them projection aware by default.

Where should these live?

The decision on where these components should live is also up in the air. GeoViews seems like a natural place for the geo-based annotators, however if they are generalized beyond the geo context then the AnnotationManager and non-geo-aware annotators could live somewhere else. HoloViews seems like a natural place but we are in the process of shrinking that library so it is a tough sell. So I see three options:

1. Put baseclasses in HoloViews and geo-aware subclasses in GeoViews
2. Limit to geo-aware implementations for now
3. Create new package for baseclasses and put geo-aware subclasses in GeoViews

My vote would be to put these components in GeoViews for the time being and punt on the geo-aware components for now.

Ping: @jbednar @kcpevey

[kcpevey]

The idea of an annotation manager sounds like a reasonable approach. You've seen how I'm currently extending the annotator classes, so as long as I can achieve that same functionality, I'm happy with this approach.

Where the annotators live is more of a discussion for your team, but we see no issue with them living in GeoViews.

[kcpevey]

I could use the annotators on a project I was working on last week so I went and looked this up again to see if they had migrated. I'll be excited when that happens! :)

[philippjfr]

Very soon, it was blocked by bokeh work until last week.

[kcpevey]

The base annotator classes now exist in holoviews.