How to add line, arrow, text

[martingluckman]

Greetings, how would I add a line, arrow or text annotation?

With kindest wishes

Martin

[rsimon]

Hi,

I'm afraid adding new shape types to Annotorious is not trivial. Here are the steps you'd need to take:

1. Add rendering capability for the new shape to the standard image version of Annotorious–see shape implementations here).
2. And/or, if necessary: add rendering capabilities to the OpenSeadragon version–see WebGL rendering code here.
3. Add a "tool" implementation: that's the code for creating a new instance for the shape. See examples for rectangle and polygon.
4. Add an "editor" implementation: that's the code for editing an existing instance of a shape when the user selects it. See examples for rectangle and polygon.

Step 3. and 4. can be done as plugins, outside of Annotorious (see here for an example). But the foundational rendering capability (steps 1 and 2) would have to be added to the core codebase.

If you really just want to draw things on an image, without using the rest of Annotorious' capabilities (like annotation payload handling, real-time capable state management, large numbers of annotations, etc.) my recommendation is usually to go with something like Konva or Fabric.js instead, which is going to be easier to customize.

[rsimon]

P.S.: I'm planning to add lines (polyline + freehand) and points as features in the near-/mid-term. I'm less sure about arrows and text. I think I'd rather handle those as special cases of point annotations (with some kind of custom representation). That would require a bit of extra thought, and architectural changes, I guess. But it could be interesting in the long run!

[rssaini01]

Jumping in just to say +1 for text annotations - that’s the main feature I’m interested in too. Being able to select or overlay text and attach notes would open up a lot of use cases. If there's a plan to treat it as a point annotation or in some other form, I’d love to follow that discussion or help however I can.

[rsimon]

To overlay text as image annotations: did you check the text overlay plugin?
https://www.npmjs.com/package/@annotorious/openseadragon-textlayer

[alejandrogolfe]

Hi!! is the freehand feature expected to be available soon? I saw that you already included the polyline feature. Thank you for your work!!

[martingluckman]

When might line and arrows be ready?

…

On Sat, 7 Jun 2025, 15:13 Rainer Simon, ***@***.***> wrote: P.S.: I'm planning to add lines (polyline + freehand) and points as features. I'm less sure about arrows and text. I think I'd rather handle those as special cases of point annotations, with some kind of custom representation. That would require a bit of an architecture addition, I guess. But it could be interesting in the long run. — Reply to this email directly, view it on GitHub <#548 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIFXO4EOQ2VNXZ53SVU5ED3CKWFBAVCNFSM6AAAAAB6ZVXJBCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGMZZGY2TIOI> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[rsimon]

I don't currently have an immediate need for lines or points myself, nor a client who wants them as features. (BTW: note that I plan to add points. I'm not planning yo add arrows as a shape type!)

So the answer is really "when the opportunity arises" ;-) I know... not a great answer. Sorry I can't put a better date on it.

[martingluckman]

Surely lines are much simpler than rectangles and polygons? I'm happy to implement this and contribute the code if you could guide me step by step to adding lines thanks!

[alexandrep-explorai]

Sure no problem. The steps are as outlined above (add shape implementations to the core; add a tool implementation; and an editor implementation). You can build off the rectangle and polygon reference implementations–those should provide good guidance for each step. (See links I added in my initial reply.)

I'm in need of a line shape implementation as well in my own application. Are the areas you targetted in the core part of the library the only places where the new shape needs to be implemented? For instance, in order to implement a new line shape for instance, I would need to:

1. Add a new LINE case to ShapeType
2. Add a new Line.svelte component implementation for the shape under /packages/annotorious/src/annotation/shapes
3. Add a new case here to the SVGAnnotationLayer for handling the ShapeType.LINE case
4. Implement a new drawLine in /packages/annotorious-openseadragon/src/annotation/pixi/stageRenderer.ts, adding a new case here to use this new function.

Or is there some other area that you omitted? Just to be sure about the amount of work that needs to be done to implement this. Thanks!

[rsimon]

I'd need to double check myself. But, yes, that should be it. One thing I forgot in the list above is that you'll also have to add the shape utils here:
https://github.com/annotorious/annotorious/tree/main/packages/annotorious/src/model/core

That's necessary to make new shape types work with the mouse hover hit detection logic.

[alexandrep-explorai]

@rsimon Question for you from my PM:

This feature is something that we really need to implement in a short delay, so if I were to implement this and submit it as a PR in the following week, how quickly can we expect it to be reviewed, merged and included in a new release? It would be ideal for us to do it this way instead of forking the repository, so we can continue getting updates and bugfixes as they come.

[rsimon]

Sure, but please keep in mind: my software is free and will always stay so. But I can't be quite as generous with personal spare time.

How long it will take depends on the PR. Longer, more complex PRs will obviously take more of my time. But it also depends on whether the code quality is ok; whether the code style matches; whether the feature is implemented in way that I feel makes sense within the overall architecture so I can confidently take over maintenance afterwards; etc.

I do all this in my spare time. Therefore, no guarantees. Thanks for understanding.

[alexandrep-explorai]

Perfectly understandable! I appreciate the quick response time and your proactiveness with this library.

[martingluckman]

@alexandrep-explorai let me know once you've implemented it, i need this feature too ASAP. thanks!

[alexandrep-explorai]

I'll make sure to update this thread if I implement it!

[martingluckman]

Wonderful looking forward to this. If you can add arrows too (its really just a simple variation of lines) that would be wonderful and very useful too.

[alexandrep-explorai]

@martingluckman @rsimon

I opened two PRs for what's been discussed here.

#550: PR in this repo to add the line shape and update the rendering capabilities so it can be rendered both with the standalone library and with the OpenSeaDragon version
annotorious/plugin-tools#3 : PR in the plugin tools repo to add a tool and an editor for the new shape.

Unfortunately all we really need for our project is the line functionality, so I didn't really do anything about arrows, but the PR may give you an idea of the work required. Although yes it would technically just a variation of a line, it can still get a little more complicated once you start thinking about the size of the arrow tip itself, and if you want to be able to control this aspect at all.

[rsimon]

Thanks for this! I took a quick glance, and this looks good overall, with a few caveats (see my comments). I'll dive deeper and test as soon as I get the chance.

[martingluckman]

If it makes it easier I'd be happy with a rudimentary arrow with a line and two small lines angled at the tip (I just need arrows to point to artefacts on manuscripts)

[martingluckman]

But I guess I can always use a line instead of an arrow - thanks so much for implementing this! Hope it gets published soon in the main repo

[martingluckman]

Is there a possibility to change the colour of the lines easily?

[rsimon]

See here: https://annotorious.dev/api-reference/drawing-style/

[martingluckman]

Yes I know about that but the user should be able to have a colour picker and select the colour?

…

On Fri, 13 Jun 2025 at 16:49, Rainer Simon ***@***.***> wrote: See here: https://annotorious.dev/api-reference/drawing-style/ — Reply to this email directly, view it on GitHub <#548 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIFXO2TMBGWYEY2B4ZUSWD3DKV2ZAVCNFSM6AAAAAB6ZVXJBCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNBVHE4TQNY> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[rsimon]

Annotorious is a JavaScript library. It provides the nuts and bolts that you need in order to build your own, custom annotation applications.

But–in case that wasn't clear–building the application is up to you! If you want to allow the user to use a color picker in your annotation, you can take any color picker component of your choice, and wire it up with a dynamic drawing style. You'd also need to store the color information in the annotation. You would usually do this via a custom body, and using a dynamic style as shown in the docs above.

[martingluckman]

Yes, I very much appreciate that approach but it's also an openseadragon plugin. It would be lovely to have it with all the features that users want and need so there is no need for each user to have to fork it and make a custom version?

…

On Fri, 13 Jun 2025 at 17:02, Rainer Simon ***@***.***> wrote: Annotorious is a JavaScript library. It provides the nuts and bolts that you need in order to build your own, custom annotation applications. But–in case that wasn't clear–building the application is up to you! If you want to allow the user to use a color picker in your annotation, you can take any color picker component of your choice, and wire it up with a dynamic drawing style. You'd also need to store the color information in the annotation. You would usually do this via a custom body, and using a dynamic style as shown in the docs above. — Reply to this email directly, view it on GitHub <#548 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIFXO2WRGPOW75ELK2NYCL3DKXOJAVCNFSM6AAAAAB6ZVXJBCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNBWGAYDQNY> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[rsimon]

Sorry, Annotorious is designed as a JavaScript utility library. You'd build your own application, and add Annotorious to your project as a dependency, just like any other library you're using in your project. (You don't need to fork it, or change the library itself, it's just something you build around.)

If you're looking for an annotation app with out-of-the-box UI, I'm afraid Annotorious (by design!) doesn't offer that, nor aims to do that.

[infovore]

You mention support for points being added - I can see in one sense how to do this, but points feel unusual because of... the many ways they could render. My case is - I have annotation data that could be points, or rects, or polys; rects and polys render as their boundaries, but you don't want points to render as a single pixel, which is the literal representation of a single x,y co-ordinate. But how points render could vary per-application - a blob, a blob with an index, a blob of varying radius, a blob with some reference to the annotation content (eg a comment). So I can see how to submit a patch for the Tool and Editor... but rendering feels like something a user might want control over? And I'm not sure where to begin there. How would you approach this?

[rsimon]

That's an excellent question – and one I don't currently have an answer for. Right now (as you say) Annotorious is extensible as far as the Tool and Editor components are concerned. But the rendering of the shape "primitives" is baked into the core.

For now, the only possibility would be to add the same kind of default rendering that exists for other shapes. (I'd vote for something like a solid circle, combined with a larger, semi-transparent halo around it.) That, obviously, means things like blobs, icons, indices etc. wouldn't be possible... But it's definitely something to keep in mind for the planning for Annotorious v4. I could imagine either some kind of framework for extending the shape rendering (in a similar way as for tools & editors) and/or a new type of "shape" which would be an icon or SVG overlay. (FWIW: the latter could already be done as an extension to v3 I guess.)