Implementation plan for Imglib2-rois 2D


So after discussing with @ctrueden, it became apparent that maybe we’re getting too bogged down with all the details at this point. And perhaps it would be beneficial to take a step back. With this goal in mind, we compiled a list of requirements for ROIs. Please review the list of requirements, and feel free to add, remove, or edit any requirements (@tpietzsch, @dietzc, @axtimwalde, @haesleinhuepf).

Additionally please note, this list does not reflect the work already done with ROIs, as a number of these requirements are already satisfied by the current ROI implementation. But rather this list is intended to be a general list of the requirements (functionalities) a ROI API should have in order to fulfill various use cases (i.e. running an algorithm on a certain subset of pixels in an image, etc.).


  • UI agnostic. (for rendering)
  • Transformable. via RealViews
    • Re-sizeable
    • Moveable
    • Rotatable
  • Location knowledge. Knowledge of position in space relative to axes
  • Shape characteristics. Knowledge of shape
    • Different ROI cases e.g. an ellipse knows its center and its axes
    • For transformed ROIs this knowledge is buried under the surface
  • Display parameters. Related relevant display information (color, fill, etc.) (optional / attached)
    • RichImage will address this
  • Independent. Able to stand alone or be related to an image
  • Iterate members. Can define a region within an image, such that pixels within that region can be sampled from the image (and only those pixels within in region can be sampled)
  • Contains. Fast inclusion/exclusion test for position
    • Consider whether boundary pixels are a separate case, besides true/false
  • Iterate boundary. Loop over all samples on boundary for discrete ROIs
  • Combine-able. Ability to combine ROIs into composite region
    • Need superclass for ROI types
  • Rasterize. Defined in real space and discrete space
  • Fuzzy ROIs. Using [0, 1] for probability of each point instead of binary true/false
  • Spatial relations. Linked to image as spatial meta-data (i.e. transformations affect both image and related ROI)
    • Should get for free with RichImage
  • Compatibility. Compatible with current labeling methods

Additional Possible Requirements:

  • Mutability

Hopefully once we have a list of requirements, it will provide a clear unified vision of what everyone wants from ROIs which in turn will help inform us about the structure of ROIs.

As always, please let me know your thoughts on this and if you have any questions.




Hi Alison,

I love the list and would hardly change anything. However, there is one thing, which may be part of the “display parameters”: It would be nice if an ROI could have name and/or a list of tags. This is often practical, but I’m not 100%ly sure if this should be part of an ROI class or RichImage or whatever.

Thanks again for your efforts! :slight_smile:


Hi Alison,

yes, I think taking a step back is a good idea. Thanks for your work and patience! Your list is a great start. Here are some thoughts and comments on individual points:

This applies only to continuous ROIs, obviously.
There should be something like Views.interpolate() to go from a discrete region to a continuous one. Actually, because every discrete ROI should be RandomAccessible<B extends BooleanType<B>> one can simply use Views.interpolate() to do this.

I’m not sure, what that means. A RandomAccessibleInterval<B extends BooleanType<B>> has its Interval boundaries to somehow locate it in space. If you want to move it around (this is all discrete), my idea was to make PositionableIterableRegion. The plan was to have Regions.positionable(Regions.iterable(RAI)) to make every arbitrary RAI<BooleanType> into such a PositionableIterableRegion. In principle of course one could always use Views to move stuff around, but the idea was that some regions might already be Positionable (for example LabelRegion) and can be moved around much more efficiently than calling Views methods for every re-positioning. At some point it would be great if the neighborhoods framework (Shape etc) and ROIs can be expressed in a unified manner. For this, going through Views would be prohibitive. That’s why we need something like Regions.positionable.

I have a strong preference for “attached”. I’m not sure whether display information should even be in imglib2-roi.

This is already implemented as Regions.sample.

I don’t think this is necessary. With (R)RAI<BooleanType> you can ask “contains” questions using RandomAccess and multiple contains queries by moving the RA around can be much more efficient than asking contains(Localizable) multiple times.

This is also a problem I have with @haesleinhuepf’s PR. The boolean operations there are build on contains and a new interface RealRandomAccessibleRealIntervalContains. I’m opposed to building on this (interface), because there is no reason that boolean operations shouldn’t work on two Img<BitType> for example.

This is already implemented in Boundary although not yet conveniently accessible through Regions.

We don’t need additional superclasses. [Real]RandomAccessible[Interval]<B extends BooleanType<B>> is sufficient. Actually, this leads to one point I would like to add to the list:

  • Compatibility with existing imglib2. It should be trivial to use for example a Img<BitType> as a ROI, e.g., combine it with a rasterized ellipsoid using a boolean operator.

Having new superclasses/interfaces would defeat this goal.

In principle Views.rasterize() should be sufficient.
We might still add Regions.rasterize() to allow shortcuts for regions that know how to rasterize more efficiently than by querying real coordinates. But in any case the results should be equivalent to Views.rasterize().

Unless there is a concrete need for it now, I would postpone this. It complicates everything considerably. In my opinion it is more realistic to get something working with boolean regions first.

Btw, @ctrueden is there a plan/timeline for RichImage? Please let me know when you need the Meta-Views stuff! (I didn’t move it to the imglib2 yet, it’s still in that janelia-hackathon-2016 repository, but it’s ready when you need it…)

best regards,

1 Like

It is currently third down my priority list, after 1) the ImageJ2 paper and 2) improved Ops type matching. I fear it will not be done before the December hackathon, and I will have to work on it during that hackathon—unless other more urgent projects materialize.

Don’t worry—I was planning to just cherry pick it out of there myself. Thank you very much for all your efforts on it.

1 Like

Nice! I wish I had the discipline to keep such a priority list!

I actually wrote it down today in response to your question. Now I hope I will be disciplined enough to keep it up-to-date. Shouldn’t be too hard, since most of those projects are substantial.


Thanks for your feedback @haesleinhuepf and @tpietzsch!

Below are some additional clarifications/questions:

True a RAI has boundaries to locate it in space. When I was creating this list I wasn’t taking into consideration what was already implemented. So the intention of this was just that we should not implement new ROIs without having some method of locating them in space. Since we’re basing the various regions off of RAIs this isn’t an issue, but kind of still a requirement for ROIs in general. (Maybe?)

True, but there’s also a possible issue with Boundary.

List<RealLocalizable> vertices = new ArrayList<RealLocalizable>();
vertices.add(new RealPoint(1d, 1d));
vertices.add(new RealPoint(5d, 1d));
vertices.add(new RealPoint(5d, 5d));
vertices.add(new RealPoint(1d, 5d));

Polygon shape = new Polygon(vertices);
IterableRandomAccessibleRegion<BoolType> rs = shape.rasterize();
Boundary<BoolType> b = new Boundary<BoolType>(rs);

So the size of rs is 16, which makes sense because it is a 4x4 square but the size of b is 12 when it should also be 16. This occurs because when you define a rectangle using Polygon points along the top and right boundary are not included in the region. And it needs to be that way, otherwise the size of rs would be off.

Still this is kind of confusing (at least to me) because if I get a RandomAccess from b and then set it to (5, 5) it evaluates to false. My intuition would be that points used to define my shape should be included in the boundary.

Though I suppose if you really wanted the points along this boundary you could use RasterizedPolygonalChain. And if you wanted points along the chain and inside the region or only points in the region that aren’t part of the chain, etc., you could just use one of the composite methods (e.g. or, subtract, etc.). Thoughts?

If we decide to leave this functionality as is, then we should ensure all region types exhibit the same behavior for consistency. :wink:

True, but then why have classes like RasterizedPolygon if there’s a Regions.rasterize()? Presumably Regions.rasterize() would do something similar to the constructor which takes a Polygon for RasterizedPolygon.

My intention with that point was more to continue the structure of having a continuous space implementation (i.e. Polygon) and a discrete space implementation (i.e. RasterizedPolygon). It seems redundant to have both, though maybe that’s not necessarily a bad thing.

Please let me know your thoughts on this, or if any of my comments/questions need further clarification.



Hello again!

I have a couple more ideas/questions/whatnots pertaining to ROIs, and I’d greatly appreciate your input on them.


  • Is there a difference between something being Positionable and something undergoing a translation?

I thought Positionable only applied to moving single points/accessors within a given space; whereas, translation would be shifting the space itself (like a region or an interval). For example, if I wanted to move one vertex of a Polygon then that vertex is Positionable but if I wanted to move the entire Polygon then that’s a translation. Is this distinction correct?

  • Would it make sense to create methods like Regions.rotate( … )?

This method would function similarly to Regions.positionable( … ). In other words, it would check if the given RealRandomAccessibleRealInterval is rotate-able and if so use its rotate method, otherwise use RealViews to do the transformation. Something similar could be done for shear, scale, etc. Provided there was a need for them.

It seems as though there’s two possible ways to do this:

  1. Use binary operators to combine multiple regions (i.e. CompositeRegionOfInterest and @haesleinhuepf’s binary operators for ROIs)
  2. Use a list of closed curves and the even/odd winding rule (i.e. GeneralPathRegionOfInterest)

I feel like option two is useful when the user knows their desired shape. For example, creating the green region in the image below. Creating this shape is easy to do using option two, but is more cumbersome to create with option one because you’d have to create multiple ROIs and combine them a few times.

On the other hand, option one is useful if someone has two regions already defined, and would now like to define a third region which is the intersection of the two.

I can’t decide which one of these options is better, so please let me know your thoughts on these two options.


  • Should there be a way of retrieving the original real space ROI from the rasterized version?

So if I create a RasterizedPolygon, should it store a reference to the Polygon it was created from? RandomAccessibleOnRealRandomAccessible does store a reference to the target RealRandomAccessible but there is no way to access it.

You could use Views.interpolate( … ) to try and reconstruct the original polygon, but it just seems like it would be easier to have the rasterized ROI keep track. Though if you transform the rasterized ROI, then you probably should use View.interpolate( … ) to retrieve the equivalent real space ROI. Thoughts?

Both the rasterize and combine-able points (specifically option 1), kind of lend themselves to an additional requirement:

Mechanism for persisting ROIs.
So if you combine, rasterize, etc. a ROI you should be able to retrieve the original ROI.

@tpietzsch, @dietzc, @axtimwalde, @haesleinhuepf please let me know your thoughts on the above. Also please feel free to let me know if you have any additional thoughts/comments/questions on ROIs, all input is welcome. :slight_smile:

And thanks again for all the feedback everyone! It has all been extremely helpful!



1 Like

Hi @awalter17,

nice hearing from you again :slight_smile:


I would not differentiate that, to keep it simple: A vertex (RealPoint?) is a Postionable and a Polygon is so as well. I’m not sure about the actual implementation, but I would say, if you translate a polygon, actually all vertices in the polygon are translated. If you translate a vertex, only its position changes.

From a theoretical point of view yes. However, I don’t remeber a project, where we needed that. So, I would put a low priority on features like rotating ROIs.


I would say, this is the standard use case.
Furthermore, the green region you showed can be created using a Polygon, right?

Maybe, @tpietzsch can tell us, why GeneralPathRegionOfInterest is deprecated?


I like this idea, but the next step would be, that every operation keeps references to their operands. At some point, this becomes hard to implement, even harder to maintain and the garbage collector may become unhappy. Again: Keep it simple. We already have algorithms (in imagej-ops) for getting polygons/meshes from binary rasterized images. It would be nice, if rasterizing and verctorizing are reversable. However, I would be happy they are almost reversable. I would put a higher priority on simplicity and maintainability of the API.

Mechanism for persisting ROIs

I kinda disagree here. If a developer wants to retrieve the original ROIs, he can keep references. If references are always kept, the heap will fill and you cannot do anything against it.
Just imagine a user using the brush tool on an image adding and removing regions for half an hour. These are a lot of binary union and subtraction operations. If we keep every single intermediate ROI, the program will become slower and slower with time.

Good luck with the project. :slight_smile: If you need external testers, or code reviewers with a far-away perspective, just let us know :wink:



Did you plan yet a mechanism for ROIs I/O ? A support for opening IJ1 ROIs would be nice also.

If you already know in which package it should live I can try to have a look depending on the status of imglib2-rois.

1 Like

Agreed, but there is so much design work to be done first to get ROIs conceptually “right” as discussed above, that I strongly suggest postponing I/O considerations. I have been involved in many ROI discussions over the past 10 years, and I/O considerations tend to pollute/complicate the design when considered too early.


Hello @tpietzsch, @dietzc, @axtimwalde, and @haesleinhuepf!

How should we handle rasterizing ROIs which don’t exist in discrete space?

For example, a 2D rectangle with corners { (0.7, 0.1), (0.79, 0.1), (0.79, 0.3), (0.7, 0.3) } or a 2D rectangle in 3D space with corners { (1, 1, 3.2), (1, 7, 3.2), (3, 7, 3.2), (3, 1, 3.2) }. Neither of those two ROIs include discrete space points (in their given spaces), so if they were rasterized using Views the returned RandomAccessible< BoolType > would never evaluate to true.

With imglib2-rois, I was just thinking of including this issue in the javadoc and having it be on the user to provide a ROI which exists in discrete space when rasterizing. Which I think would be fine, at least for now.

I was also talking with @ctrueden, about this issue and he mentioned that down the line we might want to have a way of still displaying these ROIs. For this issue, the thought was we could first transform the RealRandomAccessibleRealInterval< BoolType > to a RealRandomAccessibleRealInterval< T > where the T space value of true and false would be given to the method. Then a “fade” would be implemented, where points a certain distance away from the ROI boundary are included in this ROI (and are assigned a certain T value), via an out of bound strategy which would handle the interpolation/extrapolation. This would then allow the ROI to be displayed in discrete space.

Hopefully that makes sense, but if not please let me know and I can try to explain it in a different way. Also please let me know your thoughts on this issue as a whole, and on the display rasterization idea.

Thank you very much,



Then a “fade” would be implemented, where points a certain distance away from the ROI boundary are included in this ROI

It sounds like you’re describing a level set , which I highly recommend for rasterizing continuous ROIs, but I’m biased :). If we go in that direction, I’d be very happy to contribute / help.

The tricky cases you described can’t really be adequately represented by “classical” level sets (since the grid samples the ROI below the Nyquist rate) - and in that case, I would argue that its correct for the RandomAccessibleInterval< BoolType > to always return false. But using a level set, it will still be possible to “see that something’s there.”


Edit: We probably want a RealRandomAccessibleRealInterval< BoolType > to sometimes return true, but a RandomAccessibleInterval< BoolType > to always return false


Hello @tpietzsch, @dietzc, @axtimwalde, @ctrueden!

I’ve finished making several changes to the imglib2-rois structure on the branch shape-rois. I most likely won’t be making any additional changes to this branch until the hackathon (Feb. 21). As such, I figured now would be a good opportunity to have people look at the branch and hopefully provide me with some feedback.

Below is a list of the major changes this branch makes, as well as information on why I made some of these changes.

Changes this branch makes:

  • Modifies RealBinary(Unary)Operators:
    • Not depend on Contains interface (commit)
    • Work with any RealRandomAccessibleRealIntervals< B > (where B extends BooleanType< B >) (commit)
    • Implement Pair for RealBinaryOperator classes
  • Adds RealBinary(Unary)Operator methods to Regions (commit)
  • Removes rotation functionality from HyperRectangle/Ellipsoid, in favor of using imglib2-realtransform methods (commit 1, commit 2)
  • Adds GeomRegions (commit 1, commit 2, commit 3, commit 4)
  • Removes RasterizedPolygon, and adds general raster class (commit 1, commit 2, commit 3, commit 4, commit 5)
  • Adds method of putting a RealInterval on an AffineRealRandomAccessible (commit 1, commit 2, commit 3)
  • Modify contains(...) in HyperRectangle to include same boundary points as Polygon2D (I’m currently reading the papers mentioned in this post so we’ll see if this was actually a reasonable change) (commit 1, commit 2)
  • Creates Line region of interest (commit 1, commit 2)
  • Breaks apart and removes ROIUtils, most methods moved to Regions except getLabelingMapping which was moved to a new class Labelings (commit 1, commit 2)


  • Rotation
    • Using real-transform allows for additional transformations to the shape to just be concatenated to the matrix, as opposed to having an affine transform and then having additional rotation/translations in deeper layers
    • Drawback -> can’t keep track of interval bounds for each transformation, so instead there’s Regions.interval(…) to put interval bounds on the transformed ROI but these bounds will not update as you transform the ROI
  • Combine
    • This version of combining ROIs keeps references to each input operand, the alternate to this would be something like GeneralPath which stores curves and uses even-odd winding
    • Would make sense to eventually have both methods
    • GeneralPath method (would need to be implemented without Java-AWT)
      • Memory efficient, can’t combine existing ROIs without converting them into curves (or other general structure)
    • RealBinary(Unary)Operators
      • Not efficient if you create combined regions using many intermediate shapes, easily extends to n-dimensions, can combine any existing ROIs in several ways
  • Rasterize
    • RasterizedPolygon, RasterizedHyperRectangle, RasterizedHyperEllipsoid would have all been the same
    • RasterizedRegion is intended for ROIs with area/volume
    • Consider making a separate class for rasterizing lines and curves
  • Line/Point
    • Current issue with RealPoint not working with the rest of the API (i.e. can’t be rasterized or combined with other ROIs, because it is not a RealRandomAccessibleRealInterval)
    • Rasterizing a line using Regions.raster would (in most cases) return a RAI containing only a few points -> consider different raster method (maybe using Bresenham)

See you at the hackathon!


Hello all,

I just wanted to share some of the major decisions regarding ROIs which were made at the hackathon:

  • Separate “shapes” and RealRandomAccessibles
  • A RealMask can be the result of unary/binary operations on RealMasks (ex: And)
  • RealMasks can be affine transformed (AffineRealMask)
  • Options for whether or not a RealMask should or should not contain all points on the boundary (ex: Box)
  • Should have implementations for discrete space equivalents of RealMasks when applicable (ex: rectangles)
  • Should create Rasterizable interface for RealMasks which know how to efficiently rasterize themselves, also have additional options for raster algorithms

@tpietzsch, @dietzc, @axtimwalde, @ctrueden please feel free to add anything I missed, or correct me if needed.




Just a quick follow-up on the ROIs project: the other day, @awalter17 and I generalized RealMask to be simply Mask<L extends RealLocalizable>. So now you can have Mask<RealLocalizable> for continuous/real masks, and Mask<Localizable> for discrete/integer ones. This paves the way for discrete ROIs going forward, even if we don’t implement them all now. It also allowed us to generalize all the mask tree nodes (And, Or, Xor, etc.) to not care about whether the mask is real or integer, so it is now equally possible to generate unary/binary operation trees on either kind of mask. Work progresses on the shape-rois branch—be warned that that branch is undergoing heavy rebasing still, though.


@ctrueden @awalter17:
Do you have any design idea (or even example implementation) on how the ROIs will integrate with the ImgLabeling and Region w.r.t. sampling information from (possibly unrelated) Imgs?


Hello @stelfrich!

I haven’t done a lot with respect to sampling, but I do have adapters which can wrap Masks as RandomAccessibles (ex:

I’ve been mostly focused on creating additional real space ROIs. So in order to use them to sample from an Img you’d have to wrap them was a RealRandomAccessibleRealInterval using the adapter, then Views.raster(...), then Views.interval(...), then Regions.iterable(...), and then (finally) Regions.sample(...). The framework supports creating discrete space ROIs (Mask< Localizable >) which would be easier to use for sampling.




@tpietzsch Thank you very much for all your work on this at the hackathon! :smiley_cat:

I was looking over your changes, and I noticed that in your scheme it is not possible to retrieve the operands used to create a MaskPredicate which resulted from an or, and, etc. nor is it possible to tell which operation was performed. For example, if someone unions a rectangle and a circle there’s no way to retrieve the original circle and rectangle from the resulting MaskPredicate or figure out that the new MaskPredicate resulted from a union.

I need this functionality for my conversions in imagej-omero, though I did forget to add unit tests for this functionality on my imglib2-roi shape-rois branch :cry:. In imagej-omero if I’m given a RealMaskRealInterval to upload to OMERO, I need to check if this RealMaskRealInterval resulted from an operation between multiple MaskPredicates and if so convert the original MaskPredicates to their OMERO equivalent and then recombine them in the same way as before (but using OMERO data structures).

For example, if someone tries to upload a RealMaskRealInterval which is actually four Boxes union-ed together, then I need to be able to “unwrap” the RealMaskRealInterval into the four original Boxes and I need to know that these Boxes were union-ed.

Do you have any thoughts on how to achieve this? My thoughts are:

  1. Add four new classes (RealMaskOperationResult, RealMaskRealIntervalOperationResult, etc.), and these would have methods for retrieving operands and operation types

– OR –

  1. Add operands() and operationType() methods to MaskPredicate. Then the question is what do these methods return for things like Box, Sphere, etc
    • operands() could return null, Collections.emptyList(), Collections.singletonList(this), or …
    • operationType() could return null, an Enum, or …

Please let me know your thoughts on this. And once again thank you very much for all the work you did at the hackathon, I think the changes are a big improvement!




@awalter17 This is already there (your option 1.)

Have a look at CompositeMaskPredicate, UnaryCompositeMaskPredicate, and BinaryCompositeMaskPredicate.

I added a demo:


RealMaskRealInterval composite = s1.and(s2.minus(s3)).and(s3).or(s1.minus(s3.negate()));

it prints

leaf  (net.imglib2.troi.geom.real.ClosedSphere@7cd84586)
OR  (net.imglib2.troi.composite.DefaultBinaryCompositeRealMaskRealInterval@30dae81)
 +--AND  (net.imglib2.troi.composite.DefaultBinaryCompositeRealMaskRealInterval@1b2c6ec2)
 |   +--AND  (net.imglib2.troi.composite.DefaultBinaryCompositeRealMaskRealInterval@4edde6e5)
 |   |   +--leaf  (net.imglib2.troi.geom.real.ClosedSphere@7cd84586)
 |   |   +--MINUS  (net.imglib2.troi.composite.DefaultBinaryCompositeRealMaskRealInterval@70177ecd)
 |   |       +--leaf  (net.imglib2.troi.geom.real.ClosedSphere@1e80bfe8)
 |   |       +--leaf  (net.imglib2.troi.geom.real.ClosedSphere@66a29884)
 |   +--leaf  (net.imglib2.troi.geom.real.ClosedSphere@66a29884)
 +--MINUS  (net.imglib2.troi.composite.DefaultBinaryCompositeRealMaskRealInterval@4769b07b)
     +--leaf  (net.imglib2.troi.geom.real.ClosedSphere@7cd84586)
     +--NEGATE  (net.imglib2.troi.composite.DefaultUnaryCompositeRealMask@cc34f4d)
         +--leaf  (net.imglib2.troi.geom.real.ClosedSphere@66a29884)

The reason you didn’t see this is probably because CompositeMaskPredicate is never returned as a type. I was almost going to do that before
MaskInterval.and could return BinaryCompositeMaskInterval, etc. However, for the leafs (and therefore for the operands of a composite) I think we should leave them as general Predicate<? super T>. Therefore there needs to be instanceof checks as you descend into nested structure anyway. So…