Add science-friendly Specs II (#192)

* add `scanspec.specs.Ellipse`

* add `scanspec.specs.Polygon`

* add CR suggestions, fix CI

* test: add test_ellipse and test_polygon

* remove regions

* update plot_spec: fix docstring, add "region" outlines

* doc: update README.md

* fix docstring

* fix docstring

* chore: stricter typing in _get_boundaries

* fix README example

Author: hyperrealist

README.md

@@ -12,10 +12,9 @@ Specify step and flyscan paths in a serializable, efficient and Pythonic way usi
 - Specs like Line or Spiral
 - Optionally Snaking
 - Zip, Product and Concat to compose
-- Masks with multiple Regions to restrict
 
 Serialize the Spec rather than the expanded Path and reconstruct it on the
-server. It can them be iterated over like a [cycler][], or a stack of scan Frames
+server. It can then be iterated over like a [cycler][], or a stack of scan Frames
 can be produced and expanded Paths created to consume chunk by chunk.
 
 [cycler]: https://matplotlib.org/cycler/
@@ -31,11 +30,9 @@ An example ScanSpec of a 2D snaked grid flyscan inside a circle spending 0.4s at
 each point:
 
 ```python
-from scanspec.specs import Line, Fly
-from scanspec.regions import Circle
+from scanspec.specs import Ellipse, Fly
 
-grid = Line(y, 2.1, 3.8, 12) * ~Line(x, 0.5, 1.5, 10)
-spec = Fly(0.4 @ grid) & Circle(x, y, 1.0, 2.8, radius=0.5)
+spec = Fly(0.4 @ Ellipse(x, 1, 1, 1/9, y, 2.8, y_step=1.7/11, snake=True))
 ```
 
 Which when plotted looks like:

docs/explanations/why-stack-frames.rst

@@ -41,14 +41,6 @@ Frames object it would take 100 * 2000 * 2000 float64 = 3.2GB of RAM. The scan
 itself is likely to be executed over a long period of time, so it makes sense to
 save on the memory and calculate the squashed points as they are needed.
 
-What about Regions?
--------------------
-
-Regions will stop the regularity of the nested Frames objects, so will cause
-them to be squashed into a single Frames object. Taking our example above, if we
-`Mask` the grid with a `Circle`, then the `Linspace` in ``x`` won't have 3 points in
-each iteration, the number of points is dependent on ``y``. This means that a
-`Mask` will squash any Specs together referred to by its Regions.
 
 How does this stack relate to HDF5 Dimensions?
 ----------------------------------------------

docs/tutorials/creating-a-spec.rst

@@ -76,38 +76,20 @@ Spec of our grid we get:
     spec = Linspace("y", 3, 4, 3) * ~Linspace("x", 1, 2, 5)
 
 
-Masking with Regions
---------------------
-
-We can apply a `Mask` to only include frames where the midpoints are within a
-given `Region` using the ``&`` operator:
-
-.. example_spec::
-
-    from scanspec.specs import Linspace
-    from scanspec.regions import Circle
-
-    spec = Linspace("y", 3, 4, 3) * ~Linspace("x", 1, 2, 5) & Circle("x", "y", 1.5, 3.5, 0.6)
+Snaked Regions
+--------------
 
-
-Masking with Multiple Regions
------------------------------
-
-We can apply set-like operators to Masked Specs:
-
-- ``|``: `UnionOf` two Regions
-- ``&``: `IntersectionOf` two Regions
-- ``-``: `DifferenceOf` two Regions
-- ``^``: `SymmetricDifferenceOf` two Regions
+We can construct an `Ellipse` or a `Polygon` with a grid or a snaked grid
+by passing the optional parameter ``snake``.
 
 For example:
 
 .. example_spec::
 
-    from scanspec.specs import Linspace
-    from scanspec.regions import Circle
+    from scanspec.specs import Ellipse
+
+    spec = Ellipse("x", 0, 1, 0.1, "y", 5, 10, 0.5, snake=True)
 
-    spec = Linspace("y", 3, 4, 3) * ~Linspace("x", 1, 2, 5) & Circle("x", "y", 1.5, 3.5, 0.6) - Circle("x", "y", 1.4, 3.5, 0.2)
 
 
 Conclusion