[IconAnnotator] - Add IconAnnotator to Mark Objects with Custom Icons/Images

[dfreilich]

Description

This PR adds an IconAnnotator class, which can annotate images. For best results, the icon should be a transparent icon without a background, so that it will come up clearly against any images.

Some open questions for discussion:

1. The demo image for the annotation didn't follow the standard placement for the icon (it seems to be above the image, rather than at the center top border of the detection). I added logic to center the icon horizontally, but I wasn't sure about adding that vertically as well.
2. To what degree is it important to have color adaption for the icon annotation? It can look very nice, but it also introduces more error cases, for icons that aren't transparent, and will just show up as a colored box as a result.

I'd love to hear your thoughts on it.

A Collab notebook which demonstrates the change is here

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How has this change been tested, please provide a testcase or example of how you tested the change?

This change includes a unit test (the first created for annotations) to verify that the annotation works, and the result closely matches a so-called golden file

Docs

• Docs updated? What were the changes:

Closes #460

[CLAassistant]

All committers have signed the CLA.

[SkalskiP]

Hi @dfreilich 👋🏻 ! Thank you very much for your interest in Supervision.

• Given that we don't yet have a concrete idea for end-to-end testing of annotators, I wouldn't want to introduce it as part of this PR. I kindly ask you to remove the following files from this PR:
  • test/data/zidane.jpg
  • test/data/zidane-icon-annotated.jpg
  • test/data/icons8-diamond-50.png
  • test/annotators/test_core.py
• Your new annotator has not been included in the documentation. To do this, make the appropriate changes to annotators.md.

[dfreilich]

@SkalskiP Thanks for the review! I addressed the comments, and removed the unit tests I had created. With regards to the changes in acceptance.md, I assumed that it didn't make sense to add the IconAnnotator to the carousel at the top (like we do here:

supervision/docs/annotators.md

Lines 8 to 27 in 8599345

	=== "BoundingBox"
	```python
	import supervision as sv
	image = ...
	detections = sv.Detections(...)
	bounding_box_annotator = sv.BoundingBoxAnnotator()
	annotated_frame = bounding_box_annotator.annotate(
	scene=image.copy(),
	detections=detections
	)
	```
	<div class="result" markdown>
	{ align=center width="800" }
	</div>

) until we have an agreed upon example that's hosted on media.roboflow.com, like the rest of the examples, but I can add one if you'd like.

[LinasKo]

I've modernized and cleaned up this one, but will shift focus for now. I'll be back after the metrics are complete.
@dfreilich, if you have the time and energy, feel free to jump in, and we can include it in the next release 😉

I believe one change is needed - instead of specifying an icon at the start, we could take a Union[str, List[str]] in annotate, and either load the image once, or display different images per-object. We'll need to change the code from padding-unpadding to checking image boundaries, however, as we wouldn't know the size in advance. OR we could read all images and check the max size.

Here's my tests: Colab

Steps afterwards:

• Create an image to display in the model carousel
• Check if the docs are rendered correctly

[LinasKo]

Hey @onuralpszr,

Got a second to look at the code for this one, by any chance? 😉

[onuralpszr]

Hey @onuralpszr,

Got a second to look at the code for this one, by any chance? 😉

With pleasure :)

[LinasKo]

Thank you @dfreilich! I've edited your submission heavily, added slightly different functionality. Yet without your contribution we wouldn't have this :)

Thank you for the review, @onuralpszr!