Feat: useq.GridFromPolygon

[rlokkie]

Coming back on the discussion below:
Originally posted by @rlokkie in #42

So I want to create tile positions based on a polygon, currently I have some very wip code.
That creates a grid from the bounding box, and then retains the points-in-polygon by ray casting which seems to work*.

However I did find that the best results are achieved by using some kind of polygon-offsetting/dilation/buffering.
Also shifting the point.x,point.y with respect to the fov.width and overlap gives a cleaner result.

Offsetting is easily done using shapely, but then you import a library for 1 function.
So maybe a python rewrite in useq._utils.py would be preferred.
Or should anything that even affects (e.g. convex hull) the polygon shape happen outside of useq?

*When using reasonable number of tiles, it takes a minute or two to plot all the tiles when creating 300k+ tiles, maybe a check on tiles isn't a bad idea?

[tlambert03]

thanks for opening the issue! It's good timing, as our sample-explorer widget is making good progress... and we will also want something like this soon.

What I would like to see (and what would be in keeping with the useq pattern) would be a pure model that contains all of the information necessary to generate an iterable of points. Something like the RandomPoints model might be a good place to take inspiration (not necessarily in implementation, but perhaps in spirit). Or perhaps the wellplate plan

so, I would imagine something like this, perhaps basing off of the existing _GridPlan?

class GridFromPolygon(_GridPlan[AbsolutePosition]):
    """Yield points that fill in a polygon."""

    polygon: Annotated[list[tuple[float, float]], MinLen(3)] = Field(
        ...,
        description="List of points that define the polygon. Must be at least 3 points.",
    )
    convex_hull: bool = Field(
        False,
        description="If True, the polygon will be filled in using the convex hull of the points.",
    )

    @property
    def is_relative(self) -> bool:
        return False

    def __iter__(self) -> Iterator[AbsolutePosition]:
        ...
        # logic to fill in the polygon goes here.  Ideally, it should be a true

[rlokkie]

The plots on the left of the image are a mdasequence.gridplan.plot(), with some added matplotlib.rectangle.patches + the original Polygon.

I wanted to keep the order_mode, so the easiest to me seemed to make a list of points of the bounding box as in GridFromEdges, and then check each point if they fall in the polygon.

The minlen=3 for the polygon length is a good one.

Will make a pr when I have some time tomorrow/day after.
*edit: #224