add `get_start` and `get_end` methods for `Region` annotaiton type (and subtypes)

[keighrim]

New Feature Summary

As Region types can have either (start & end) props or just targets prop, I'd like to provide helper functions to return the anchor points regardless of how those anchor are encoded as annotation properties. Namely, for annotations with start and end, this new methods simply return those. For those with targets`, it should grab the first and last elements from the targets list and return underlying anchor values.

Related

No response

Alternatives

No response

Additional context

No response

[keighrim]

While working on this by implementing a general get_anchor_point helper method, I found that it is very hard to implement due to annotation objects that have two or more "anchor" properties (example, BoundingBox has timePoint and coordinates)

Here's the draft implementation

class Mmif(MmifObject):
    ...
    def get_anchor_point(self, ann: Annotation, start: bool = True) -> Union[int, float, Tuple[int, int]]:
        # TODO (krim @ 2/5/24): Update the return type once timeunits are unified to `ms` as integers
        """
        Retrieves the anchor point of the annotation.
        
        :param ann: An Annotation object that has an anchor point. Namely a subtype of `Region` vocabulary type.
        :param start: If True, returns the start anchor point. Otherwise, returns the end anchor point. N/A for `timePoint` anchors.
        :return: the anchor point of the annotation. 1d for linear regions (time, text) and 2d for spatial regions (polygons)
        """
        props = ann.properties
        if 'timePoint' in props:
            return ann.get_property('timePoint')
        elif 'coordinates' in props:
            return ann.get_property('coordinates')[0 if start else -1]
        elif 'targets' in props:
            # TODO (krim @ 2/5/24): not sure if this is the correct way to pick the "first" (or "last") target
            # since the targets list is not guaranteed to be sorted
            # However, due the recursive nature of this method, it is likely impossible
            # to get all `start` (or `end`) values of the targets and then pick the first (or last) one
            target_id = ann.get_property('targets')[0 if start else -1]
            if Mmif.id_delimiter in target_id:
                target = self.get_annotation_by_id(*target_id.split(Mmif.id_delimiter))
            else:
                target = self.get_annotation_by_id(ann.parent, target_id)
            return self.get_anchor_point(target, start=start)
        elif (start and 'start' in props) or (not start and 'end' in props):
            return ann.get_property('start' if start else 'end')
        else:
            raise ValueError(f"{ann.id} ({ann.at_type}) does not have a valid anchor point. Is it a valid 'Region' type?")

I was never fond of the idea of these multi-modal hybrid annotations, and there is ongoing effort to "fix" our past practices of using such hybrid annotations (clamsproject/app-tesseractocr-wrapper#19, clamsproject/app-east-textdetection#8). In the long run, particularly when we become more serious about implementing clamsproject/clams-vocabulary#15 (comment), I think having "primitive" base anchor types for different modalities will benefit us by providing cleaner logical relations between annotation. But for now we don't have such specification in the MMIF, hence the hybrid BoundingBox is totally legitimate.

Given that, the implementation in the current dev cycle will be limited to 1-d anchors (time and text).

[marcverhagen]

I think we should have a discussion on this soon so we can put the anchoring/alignment discussion to bed.

Looking at #254 I see code that looks fine at first sight, but I am not clear on why the checks failed, nor do I understand some of the comments in the code.

The general idea of anchors is nice, but it seems possible to include start/end, targets, timePoint, coordinates and Alignments, which makes it perhaps tricky to get this right. Also sounds like MMIF 2.0.0 to me.

[keighrim]

One problem with the current implementation I found is that when a TimeFrame doesn't have explicit timeUnit, start, and end properties, but instead of targets list with underlying TimePoint annotations, one can get the start and end points in numerics by calling tf.get('start') or some equivalent - but there can be no clear unit specified for that numbers.

This will go away if you only allow milliseconds as THE timeunit within the MMIF (clamsproject/clams-vocabulary#15), but until then, there should be some workaround for this problem.