Generator rewrite

docs/architecture.rst

@@ -1,8 +1,11 @@
 Architecture
 ============
 
-Every scan point generator inherits from the ScanPointGenerator baseclass. This
-baseclass provides the following API:
+Scan points are produced by a :ref:`compoundgenerator` that wraps base generators,
+:ref:`excluders` and :ref:`mutators`.
+
+All Generators inherit from the Generator baseclass, which provides the
+following API:
 
 .. module:: scanpointgenerator
 
@@ -18,13 +21,11 @@ API:
 Using the API
 -------------
 
-You would use a generator in a step scan like this::
-
-    >>> for point in generator.iterator():
-    >>>     for mname, mpos in point.positions():
-    >>>         motors[mname].move(mpos)
-    >>>     det.write_data_to_index(point.indexes)
-
-
-
+A basic use case that uses two generators looks like this::
 
+    cgen = CompoundGenerator([outer_generator, inner_generator], [], [])
+    cgen.prepare()
+    for point in cgen.iterator():
+        for mname, mpos in point.positions():
+            motors[mname].move(mpos)
+        det.write_data_to_index(point.indexes)

docs/compoundgenerator.rst

@@ -1,3 +1,5 @@
+.. _compoundgenerator:
+
 Compound Generator
 ==================
 
@@ -16,7 +18,8 @@ line scan inside it with 5 points.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, CompoundGenerator, plot_generator
+    from scanpointgenerator import LineGenerator, CompoundGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     xs = LineGenerator("x", "mm", 0.0, 0.5, 5, alternate_direction=False)
     ys = LineGenerator("y", "mm", 0.0, 0.5, 4)
@@ -34,9 +37,32 @@ be run in reverse to give a snake scan.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, CompoundGenerator, plot_generator
+    from scanpointgenerator import LineGenerator, CompoundGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     xs = LineGenerator("x", "mm", 0.0, 0.5, 5, alternate_direction=True)
     ys = LineGenerator("y", "mm", 0.0, 0.5, 4)
     gen = CompoundGenerator([ys, xs], [], [])
     plot_generator(gen)
+
+
+.. _compoundgenerator_restrictions:
+
+Restrictions
+------------
+
+:ref:`excluders` must be defined on axes that are given by consecutive
+generators. Generators with axes filtered by an excluder must also have a
+common ``alternate_direction`` setting. An exception is made for the outermost
+generator as it is not repeated.
+
+The following is `not` legal::
+
+    from scanpointgenerator import LineGenerator, CompoundGenerator, \
+    Excluder, CircularROI
+
+    xs = LineGenerator("x", "mm", 0, 1, 2)
+    ys = LineGenerator("y", "mm", 0, 1, 2)
+    zs = LineGenerator("z", "mm", 0, 1, 2)
+    exc = Excluder(CircularROI([0, 0], 1), ["x", "z"])
+    gen = CompoundGenerator([zs, ys, xs], [exc], []) # xs and zs are not consecutive

docs/creating.rst

@@ -3,7 +3,8 @@ Creating a Generator
 
 The idea of CompoundGenerator is that you can combine generators, excluders
 and mutators arbitrarily. The following will show some more extensive examples
-to show the capabilities of scanpointgenerator.
+to show the capabilities of scanpointgenerator. Remember to account for the
+restrictions specified in :ref:`compoundgenerator_restrictions`.
 
 
 A spiral scan with an offset rectangular roi overlay and randomly offset
@@ -13,8 +14,8 @@ points in the y direction
     :include-source:
 
     from scanpointgenerator import LineGenerator, SpiralGenerator, \
-    CompoundGenerator, Excluder, RandomOffsetMutator, plot_generator
-    from scanpointgenerator.rectangular_roi import RectangularROI
+    CompoundGenerator, Excluder, RandomOffsetMutator, RectangularROI
+    from scanpointgenerator.plotgenerator import plot_generator
 
     spiral = SpiralGenerator(["x", "y"], "mm", [0.0, 0.0], 10.0,
                              alternate_direction=True)
@@ -36,6 +37,7 @@ A spiral scan at each point of a line scan with alternating direction
     spiral = SpiralGenerator(["x", "y"], "mm", [0.0, 0.0], 1.2,
                              alternate_direction=True)
     gen = CompoundGenerator([line, spiral], [], [])
+    gen.prepare()
 
     for point in gen.iterator():
         for axis, value in point.positions.items():
@@ -57,21 +59,20 @@ A spiral scan at each point of a line scan with alternating direction
     {'y': 0.695, 'x': -0.56, 'z': 20.0}
     {'y': 0.992, 'x': 0.361, 'z': 20.0}
 
-Three nested line scans with an excluder operating on the innermost and
-outermost axes
+Three nested line scans with an excluder operating on the two innermost axes
 
 .. plot::
     :include-source:
 
     from scanpointgenerator import LineGenerator, CompoundGenerator, \
-    Excluder
-    from scanpointgenerator.circular_roi import CircularROI
+    Excluder, CircularROI
 
     line1 = LineGenerator("x", "mm", 0.0, 2.0, 3)
     line2 = LineGenerator("y", "mm", 0.0, 1.0, 2)
     line3 = LineGenerator("z", "mm", 0.0, 1.0, 2)
-    circle = Excluder(CircularROI([1.0, 1.0], 1.0), ["x", "z"])
+    circle = Excluder(CircularROI([1.0, 1.0], 1.0), ["x", "y"])
     gen = CompoundGenerator([line3, line2, line1], [circle], [])
+    gen.prepare()
 
     for point in gen.iterator():
         print(point.positions)
@@ -86,4 +87,3 @@ outermost axes
     {'y': 1.0, 'x': 0.0, 'z': 1.0}
     {'y': 1.0, 'x': 1.0, 'z': 1.0}
     {'y': 1.0, 'x': 2.0, 'z': 1.0}
-

docs/excluders.rst

@@ -1,3 +1,5 @@
+.. _excluders:
+
 Excluders
 =========
 
@@ -18,8 +20,8 @@ Here we use a CircularROI to filter the points of a snake scan
     :include-source:
 
     from scanpointgenerator import LineGenerator, CompoundGenerator, \
-    Excluder, plot_generator
-    from scanpointgenerator.circular_roi import CircularROI
+    Excluder, CircularROI
+    from scanpointgenerator.plotgenerator import plot_generator
 
     x = LineGenerator("x", "mm", 0.0, 4.0, 5, alternate_direction=True)
     y = LineGenerator("y", "mm", 0.0, 3.0, 4)
@@ -33,12 +35,12 @@ And with the excluder applied
     :include-source:
 
     from scanpointgenerator import LineGenerator, CompoundGenerator, \
-    Excluder, plot_generator
-    from scanpointgenerator.circular_roi import CircularROI
+    Excluder, CircularROI
+    from scanpointgenerator.plotgenerator import plot_generator
 
     x = LineGenerator("x", "mm", 0.0, 4.0, 5, alternate_direction=True)
     y = LineGenerator("y", "mm", 0.0, 3.0, 4)
     circle = Excluder(CircularROI([2.0, 1.0], 2.0), ["x", "y"])
     excluder = Excluder(circle, ['x', 'y'])
     gen = CompoundGenerator([y, x], [circle], [])
-    plot_generator(gen, circle)
+    plot_generator(gen, circle)

docs/index.rst

@@ -15,7 +15,6 @@ Table of Contents
    linegenerator
    spiralgenerator
    lissajousgenerator
-   arraygenerator
 
 .. toctree::
    :maxdepth: 1

docs/linegenerator.rst

@@ -17,7 +17,8 @@ of each capture point.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, plot_generator
+    from scanpointgenerator import LineGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     gen = LineGenerator("x", "mm", 0.0, 1.0, 5)
     plot_generator(gen)
@@ -27,7 +28,8 @@ LineGenerator is N dimensional; just pass in ND lists for name, start and stop.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, plot_generator
+    from scanpointgenerator import LineGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     gen = LineGenerator(["x", "y"], "mm", [1.0, 2.0], [5.0, 10.0], 5)
     plot_generator(gen)

docs/lissajousgenerator.rst

@@ -15,7 +15,8 @@ will be scanned over a 3x4 lobe Lissajous curve with filling a 1x1mm rectangle.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LissajousGenerator, plot_generator
+    from scanpointgenerator import LissajousGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     box = dict(centre=[0.0, 0.0], width=1.0, height=1.0)
     gen = LissajousGenerator(['x', 'y'], "mm", box=box, num_lobes=3, num_points=50)
@@ -27,8 +28,9 @@ visible. The following plot is for 10x11 lobes with the default number of points
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LissajousGenerator, plot_generator
+    from scanpointgenerator import LissajousGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     box = dict(centre=[0.0, 0.0], width=1.0, height=1.0)
     gen = LissajousGenerator(['x', 'y'], "mm", box=box, num_lobes=20)
-    plot_generator(gen, show_indexes=False)
+    plot_generator(gen, show_indexes=False)

docs/mutators.rst

@@ -1,3 +1,5 @@
+.. _mutators:
+
 Mutators
 ========
 
@@ -18,7 +20,8 @@ apply it to a snake scan
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, CompoundGenerator, plot_generator
+    from scanpointgenerator import LineGenerator, CompoundGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     xs = LineGenerator("x", "mm", 0.0, 0.5, 5, alternate_direction=True)
     ys = LineGenerator("y", "mm", 0.0, 0.5, 4)
@@ -30,10 +33,25 @@ And with the random offset
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, CompoundGenerator, RandomOffsetMutator, plot_generator
+    from scanpointgenerator import LineGenerator, CompoundGenerator, RandomOffsetMutator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     xs = LineGenerator("x", "mm", 0.0, 0.5, 5, alternate_direction=True)
     ys = LineGenerator("y", "mm", 0.0, 0.5, 4)
-    random_offset = RandomOffsetMutator(seed=1, axes = ["x", "y"], max_offset=dict(x=0.05, y=0.05))
+    random_offset = RandomOffsetMutator(seed=12345, axes = ["x", "y"], max_offset=dict(x=0.05, y=0.05))
     gen = CompoundGenerator([ys, xs], [], [random_offset])
-    plot_generator(gen)
+    plot_generator(gen)
+
+
+Example with a spiral
+
+.. plot::
+    :include-source:
+
+    from scanpointgenerator import SpiralGenerator, CompoundGenerator, RandomOffsetMutator
+    from scanpointgenerator.plotgenerator import plot_generator
+
+    spiral = SpiralGenerator(["x", "y"], ["mm", "mm"], [0., 0.], 5.0, 1.25)
+    random_offset = RandomOffsetMutator(seed=12345, axes = ["x", "y"], max_offset=dict(x=0.2, y=0.2))
+    gen = CompoundGenerator([spiral], [], [random_offset])
+    plot_generator(gen)

docs/serialisation.rst

@@ -123,8 +123,8 @@ As an example of serialising, here is a simple snake scan.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, CompoundGenerator, \
-        plot_generator
+    from scanpointgenerator import LineGenerator, CompoundGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     x = LineGenerator("x", "mm", 0.0, 4.0, 5, alternate_direction=True)
     y = LineGenerator("y", "mm", 0.0, 3.0, 4)
@@ -137,8 +137,8 @@ It is the same after being serialised and deserialised.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import LineGenerator, CompoundGenerator, \
-        plot_generator
+    from scanpointgenerator import LineGenerator, CompoundGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     x = LineGenerator("x", "mm", 0.0, 4.0, 5, alternate_direction=True)
     y = LineGenerator("y", "mm", 0.0, 3.0, 4)

docs/spiralgenerator.rst

@@ -15,7 +15,8 @@ will be scanned in a spiral filling a circle of radius 5mm.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import SpiralGenerator, plot_generator
+    from scanpointgenerator import SpiralGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     gen = SpiralGenerator(["x", "y"], "mm", [0.0, 0.0], 5.0)
     plot_generator(gen)
@@ -25,7 +26,8 @@ In this example the spiral is scaled to be more sparse.
 .. plot::
     :include-source:
 
-    from scanpointgenerator import SpiralGenerator, plot_generator
+    from scanpointgenerator import SpiralGenerator
+    from scanpointgenerator.plotgenerator import plot_generator
 
     gen = SpiralGenerator(["x", "y"], "mm", [0.0, 0.0], 5.0, scale=2.0)
-    plot_generator(gen)
+    plot_generator(gen)