172 create duration spec and update fly and step

README.md

@@ -31,11 +31,11 @@ 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.specs import Line, Fly
 from scanspec.regions import Circle
 
 grid = Line(y, 2.1, 3.8, 12) * ~Line(x, 0.5, 1.5, 10)
-spec = fly(grid, 0.4) & Circle(x, y, 1.0, 2.8, radius=0.5)
+spec = Fly(0.4 @ grid) & Circle(x, y, 1.0, 2.8, radius=0.5)
 ```
 
 Which when plotted looks like:
@@ -48,8 +48,8 @@ Scan points can be iterated through directly for convenience:
 for point in spec.midpoints():
     print(point)
 # ...
-# {'y': 3.1818181818181817, 'x': 0.8333333333333333, 'DURATION': 0.4}
-# {'y': 3.1818181818181817, 'x': 0.7222222222222222, 'DURATION': 0.4}
+# {'y': 3.1818181818181817, 'x': 0.8333333333333333}
+# {'y': 3.1818181818181817, 'x': 0.7222222222222222}
 ```
 
 or a Path created from the stack of Frames and chunks of a given length
@@ -60,12 +60,13 @@ from scanspec.core import Path
 
 stack = spec.calculate()
 len(stack[0])  # 44
-stack[0].axes()  # ['y', 'x', 'DURATION']
+stack[0].axes()  # ['y', 'x']
 
 path = Path(stack, start=5, num=30)
 chunk = path.consume(10)
-chunk.midpoints  # {'x': <ndarray len=10>, 'y': <ndarray len=10>, 'DURATION': <ndarray len=10>}
+chunk.midpoints  # {'x': <ndarray len=10>, 'y': <ndarray len=10>}
 chunk.upper  # bounds are same dimensionality as positions
+chunk.duration # duration of each frame
 ```
 
 <!-- README only content. Anything below this line won't be included in index.md -->

docs/explanations/technical-terms.rst

@@ -30,7 +30,7 @@ as `Dimension.lower`, `Dimension.midpoints` and `Dimension.upper`.
 .. _frame_:
 
 Dimension
------
+---------
 
 A vector of three `Points <point_>` in scan space: lower, midpoint, upper. They
 describe the trajectory that should be taken while a detector is active while
@@ -40,7 +40,7 @@ section.
 .. _stack_:
 
 Stack of Dimensions
----------------
+-------------------
 
 A repeatable, possibly snaking, series of `Dimension` along a number of `Axes
 <axis_>`. In the diagram above, the whole Line produces a single `Dimension`

docs/explanations/why-squash-can-change-path.rst

@@ -17,7 +17,7 @@ is the case.
     will fail with `ValueError`
 
 Squash unsnaked axis into a snaked Dimensions
------------------------------------------
+---------------------------------------------
 
 Squashing Dimension objects together will take the snake setting of the slowest
 moving Dimension object in the squash. If this squashed Dimension object is nested

docs/how-to/iterate-a-spec.rst

@@ -30,10 +30,11 @@ If you need to do a fly scan
 
 If you are conducting a fly scan then you need the frames that the motor moves
 through. You can get that from the lower and upper bounds of each point. If the
-scan is small enough to fit in memory on the machine you can use the `Spec.frames()`
+scan is small enough to fit in memory on the machine you can use the `Fly(spec).frames()`
 method to produce a single `Dimension` object containing the entire scan:
 
->>> segment = spec.frames()
+>>> from scanspec.specs import Fly
+>>> segment = Fly(spec).frames()
 >>> len(segment)
 3
 >>> segment.lower
@@ -89,8 +90,8 @@ You may need to know where there is a gap between points, so that you can do
 something in the turnaround. For example, if we take the x axis of a grid scan,
 you can see it snakes back and forth:
 
->>> from scanspec.specs import Line, fly
->>> grid = fly(Line("y", 0, 1, 2) * ~Line("x", 1, 2, 3), 0.1)
+>>> from scanspec.specs import Line, Fly
+>>> grid = Fly(0.1 @ (Line("y", 0, 1, 2) * ~Line("x", 1, 2, 3)))
 >>> chunk = grid.frames()
 >>> chunk.midpoints["x"]
 array([1. , 1.5, 2. , 2. , 1.5, 1. ])

pyproject.toml

@@ -46,6 +46,7 @@ dev = [
     "sphinxcontrib-openapi",
     "tox-direct",
     "types-mock",
+    "Pillow==11.0.0",
 ]
 
 [project.scripts]

schema.json

@@ -545,6 +545,72 @@
                 "title": "Concat",
                 "description": "Concatenate two Specs together, running one after the other.\n\nEach Dimension of left and right must contain the same axes. Typically\nformed using `Spec.concat`.\n\n.. example_spec::\n\n    from scanspec.specs import Line\n\n    spec = Line(\"x\", 1, 3, 3).concat(Line(\"x\", 4, 5, 5))"
             },
+            "ConstantDuration_str_-Input": {
+                "properties": {
+                    "constant_duration": {
+                        "type": "number",
+                        "title": "Constant Duration",
+                        "description": "The value at each point"
+                    },
+                    "spec": {
+                        "anyOf": [
+                            {
+                                "$ref": "#/components/schemas/Spec-Input"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "description": "Spec contaning the path to be followed"
+                    },
+                    "type": {
+                        "type": "string",
+                        "const": "ConstantDuration",
+                        "title": "Type",
+                        "default": "ConstantDuration"
+                    }
+                },
+                "additionalProperties": false,
+                "type": "object",
+                "required": [
+                    "constant_duration"
+                ],
+                "title": "ConstantDuration",
+                "description": "A special spec used to hold information about the duration of each frame."
+            },
+            "ConstantDuration_str_-Output": {
+                "properties": {
+                    "constant_duration": {
+                        "type": "number",
+                        "title": "Constant Duration",
+                        "description": "The value at each point"
+                    },
+                    "spec": {
+                        "anyOf": [
+                            {
+                                "$ref": "#/components/schemas/Spec-Output"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "description": "Spec contaning the path to be followed"
+                    },
+                    "type": {
+                        "type": "string",
+                        "const": "ConstantDuration",
+                        "title": "Type",
+                        "default": "ConstantDuration"
+                    }
+                },
+                "additionalProperties": false,
+                "type": "object",
+                "required": [
+                    "constant_duration"
+                ],
+                "title": "ConstantDuration",
+                "description": "A special spec used to hold information about the duration of each frame."
+            },
             "DifferenceOf_str_-Input": {
                 "properties": {
                     "left": {
@@ -657,6 +723,48 @@
                 "title": "Ellipse",
                 "description": "Mask contains points of axis within an xy ellipse of given radius.\n\n.. example_spec::\n\n    from scanspec.regions import Ellipse\n    from scanspec.specs import Line\n\n    grid = Line(\"y\", 3, 8, 10) * ~Line(\"x\", 1 ,8, 10)\n    spec = grid & Ellipse(\"x\", \"y\", 5, 5, 2, 3, 75)"
             },
+            "Fly_str_-Input": {
+                "properties": {
+                    "spec": {
+                        "$ref": "#/components/schemas/Spec-Input",
+                        "description": "Spec contaning the path to be followed"
+                    },
+                    "type": {
+                        "type": "string",
+                        "const": "Fly",
+                        "title": "Type",
+                        "default": "Fly"
+                    }
+                },
+                "additionalProperties": false,
+                "type": "object",
+                "required": [
+                    "spec"
+                ],
+                "title": "Fly",
+                "description": "Spec that represents a fly scan."
+            },
+            "Fly_str_-Output": {
+                "properties": {
+                    "spec": {
+                        "$ref": "#/components/schemas/Spec-Output",
+                        "description": "Spec contaning the path to be followed"
+                    },
+                    "type": {
+                        "type": "string",
+                        "const": "Fly",
+                        "title": "Type",
+                        "default": "Fly"
+                    }
+                },
+                "additionalProperties": false,
+                "type": "object",
+                "required": [
+                    "spec"
+                ],
+                "title": "Fly",
+                "description": "Spec that represents a fly scan."
+            },
             "GapResponse": {
                 "properties": {
                     "gap": {
@@ -1343,6 +1451,12 @@
                     {
                         "$ref": "#/components/schemas/Line_str_"
                     },
+                    {
+                        "$ref": "#/components/schemas/Fly_str_-Input"
+                    },
+                    {
+                        "$ref": "#/components/schemas/ConstantDuration_str_-Input"
+                    },
                     {
                         "$ref": "#/components/schemas/Static_str_"
                     },
@@ -1354,6 +1468,8 @@
                     "propertyName": "type",
                     "mapping": {
                         "Concat": "#/components/schemas/Concat_str_-Input",
+                        "ConstantDuration": "#/components/schemas/ConstantDuration_str_-Input",
+                        "Fly": "#/components/schemas/Fly_str_-Input",
                         "Line": "#/components/schemas/Line_str_",
                         "Mask": "#/components/schemas/Mask_str_-Input",
                         "Product": "#/components/schemas/Product_str_-Input",
@@ -1392,6 +1508,12 @@
                     {
                         "$ref": "#/components/schemas/Line_str_"
                     },
+                    {
+                        "$ref": "#/components/schemas/Fly_str_-Output"
+                    },
+                    {
+                        "$ref": "#/components/schemas/ConstantDuration_str_-Output"
+                    },
                     {
                         "$ref": "#/components/schemas/Static_str_"
                     },
@@ -1403,6 +1525,8 @@
                     "propertyName": "type",
                     "mapping": {
                         "Concat": "#/components/schemas/Concat_str_-Output",
+                        "ConstantDuration": "#/components/schemas/ConstantDuration_str_-Output",
+                        "Fly": "#/components/schemas/Fly_str_-Output",
                         "Line": "#/components/schemas/Line_str_",
                         "Mask": "#/components/schemas/Mask_str_-Output",
                         "Product": "#/components/schemas/Product_str_-Output",