for release 4.1

JuliaGraphics · Jul 31, 2024 · 11d4d33 · 11d4d33
1 parent 086102e
commit 11d4d33
Show file tree

Hide file tree

Showing 23 changed files with 284 additions and 138 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,12 +1,13 @@
 # Changelog
 
-## [v4.1] - forthcoming
+## [v4.1] - 2024-07-31
 
 ### Added
 
 - triangular grids
 - `squirclepath()`
 - `rule(pt1, pt2)`
+- `polysidelengths()`
 
 ### Changed
 

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,14 +1,10 @@
 [deps]
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
-Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
 Luxor = "ae8d54c2-7ccd-5906-9d76-62fc9837b5bc"
 MathTeXEngine = "0a4f8689-d25c-4efe-a92b-7142dfc1aa53"
 
 [compat]
 Colors = "0.12"
 Documenter = "1"
-DocumenterTools = "0.1"
-Images = "0.26.1"
 MathTeXEngine = "0.5, 0.6"
diff --git a/docs/src/assets/figures/minifb-pi-1.png b/docs/src/assets/figures/minifb-pi-1.png
diff --git a/docs/src/assets/figures/minifb-pi.png b/docs/src/assets/figures/minifb-pi.png
diff --git a/docs/src/assets/figures/playing-pixels-1.png b/docs/src/assets/figures/playing-pixels-1.png
diff --git a/docs/src/assets/figures/playing-pixels-2.png b/docs/src/assets/figures/playing-pixels-2.png
diff --git a/docs/src/assets/figures/playing-pixels-3.png b/docs/src/assets/figures/playing-pixels-3.png
diff --git a/docs/src/assets/figures/playing-pixels-4.png b/docs/src/assets/figures/playing-pixels-4.png
diff --git a/docs/src/assets/figures/playing-pixels-5.png b/docs/src/assets/figures/playing-pixels-5.png
diff --git a/docs/src/howto/createdrawings.md b/docs/src/howto/createdrawings.md
@@ -6,7 +6,7 @@ To create a drawing, and optionally specify the filename, type, and dimensions,
 
 To finish a drawing and close the file, use [`finish`](@ref).
 
-Ff the drawing doesn't appear automatically in your notebook or editing environment, you can type [`preview`](@ref) to see it.
+If the drawing doesn't appear automatically in your notebook or editing environment, you can type [`preview`](@ref) to see it.
 
 ![jupyter](../assets/figures/jupyter.png)
 
@@ -18,6 +18,20 @@ If you're using VS Code, then PNG and SVG drawings should automatically appear i
 
     SVGs are text-based, and can get quite big. Up to a certain size, SVGs will preview as easily and quickly as PNGs. As they get larger, though, they'll take longer, and it won't be long before they'll take longer to preview than to create in the first place. Very large drawings in SVG format might not display at all.
 
+In Julia, the result of the most recently evaluated expression is usually displayed in a suitable form for the current environment. If the most recent expression was a Luxor drawing, it will probably be displayed somewhere, unless you're working in the REPL. So  this code:
+
+```julia
+Drawing(100, 100, :png)
+origin()
+sethue("green")
+circle(O, 10, :fill)
+finish()
+preview()
+println("finished")
+```
+
+won't display a drawing with a circle - the most recent result is returned by `println()`, not `preview()`. 
+
 ## Quick drawings with macros
 
 The [`@draw`](@ref), [`@svg`](@ref), [`@drawsvg`](@ref), [`@png`](@ref), and [`@pdf`](@ref) macros are designed to let you quickly create graphics without having to provide the usual boiler-plate functions.
@@ -96,7 +110,7 @@ Drawing(width, height, surfacetype, [filename])
 
 lets you supply `surfacetype` as a symbol (`:svg`, `:png`, `:image`, or `:rec`). This creates a new drawing of the given surface type and stores the image only in memory if no `filename` is supplied.
 
-The [`@draw`](@ref) macro (equivalent to `Drawing(..., :png)` creates a PNG drawing in-memory (not saved in a file). You should see it displayed if you're working in a suitable environment (VSCode, Jupyter, Pluto).
+The [`@draw`](@ref) macro (equivalent to `Drawing(..., :png)`) creates a PNG drawing in-memory (not saved in a file). You should see it displayed if you're working in a suitable environment (VSCode, Jupyter, Pluto).
 
 The SVG equivalent of `@draw` is [`@drawsvg`](@ref).
 
@@ -184,7 +198,11 @@ end
 
 ### Using Jupyter notebooks (IJulia and Interact)
 
-Currently, you should use an in-memory SVG drawing to display graphics if you're using Interact.jl. This example provides an HSB color widget.
+This example uses Interact.jl to provide an HSB color widget.
+
+!!! note
+
+    Interact.jl may be obsolete by the time you read this.
 
 ```julia
 using Interact, Colors, Luxor
@@ -235,7 +253,7 @@ finish()
 As a standard Julia array, `A` will be shown as an image in your notebook or editor if you're using Images.jl.
 
 !!! note
-
+    
     In this example the array uses Julian "column-major" array addressing. Luxor functions use the `Point` type on a Cartesian coordinate system, where the origin is (by default) at the top left of the drawing. Locations along the x-axis correspond to the column indices of the array, locations along the y-axis correspond to the rows of the array (until you use the `origin()` function, for example).
 
 You can also create a pixel array on a PNG drawing when saved as a file:

diff --git a/docs/src/howto/polygons.md b/docs/src/howto/polygons.md
@@ -10,35 +10,35 @@ You can store a path in a Path type, which contains path elements.
 
 Luxor also provides a BezierPath type, which is an array of four-point tuples, each of which is a Bézier cubic curve section.
 
-|create                        |convert                    |draw                     |info                     |edit                        |
-|:---                          |:---                       |:---                     |:---                     |:---                        |
-| *polygons*                   |                           |                         |                         |                            |
-|[`ngon`](@ref)                |[`polysmooth`](@ref)       |[`poly`](@ref)           |[`isinside`](@ref)       |[`simplify`](@ref)          |
-|[`ngonside`](@ref)            |[`polytopath`](@ref)       |[`prettypoly`](@ref)     |[`polyperimeter`](@ref)  |[`polysplit`](@ref)         |
-|[`star`](@ref)                |[`polyintersect`](@ref)    |[`polysmooth`](@ref)     |[`polyarea`](@ref)       |[`polyportion`](@ref)       |
-|[`polycross`](@ref)           |                           |                         |[`polycentroid`](@ref)   |[`polyremainder`](@ref)     |
-|[`offsetpoly`](@ref)          |                           |                         |[`BoundingBox`](@ref)    |[`polysortbyangle`](@ref)   |
-|[`hypotrochoid`](@ref)        |                           |                         |[`ispolyclockwise`](@ref)|[`polysortbydistance`](@ref)|
-|[`epitrochoid`](@ref)         |                           |                         |[`ispolyconvex`](@ref)   |[`polyclip`](@ref)          |
-|[`polyrotate!`](@ref)         |                           |                         |[`ispointonpoly`](@ref)  |[`polymove!`](@ref)         |
-|[`polyfit`](@ref)             |                           |                         |                         |[`polyscale!`](@ref)        |
-|[`polyhull`](@ref)            |                           |                         |                         |[`polyreflect!`](@ref)      |
-|[`polysuper`](@ref)           |                           |                         |                         |[`polysample`](@ref)        |
-|[`polybspline`](@ref)         |                           |                         |                         |[`polytriangulate`](@ref)   |
-|                              |                           |                         |                         |[`insertvertices!`](@ref)   |
-|                              |                           |                         |                         |[`polymorph`](@ref)         |
-|                              |                           |                         |                         |                            |
-|                              |                           |                         |                         |                            |
-| *paths*                      |                           |                         |                         |                            |
-|[`storepath`](@ref)           |                           |                         |                         |                            |
-|[`getpath`](@ref)             |[`pathtopoly`](@ref)       |[`drawpath`](@ref)       |[`pathlength`](@ref)     |[`pathsample`](@ref)        |
-|[`getpathflat`](@ref)         |                           |                         |                         |                            |
-| *Bezier paths*               |                           |                         |                         |                            |
-|[`makebezierpath`](@ref)      |[`pathtobezierpaths`](@ref)|[`drawbezierpath`](@ref) |                         |[`trimbezier`](@ref)        |
-|[`pathtobezierpaths`](@ref)   |[`bezierpathtopoly`](@ref) |[`brush`](@ref)          |                         |[`splitbezier`](@ref)       |
-|`BezierPath`                  |[`bezierpathtopath`](@ref) |[`bezigon`](@ref)        |                         |                            |
-|`BezierPathSegment`           |                           |                         |                         |                            |
-|[`beziersegmentangles`](@ref) |                           |                         |                         |                            |
+|create                        |convert                    |draw                     |info                      |edit                        |
+|:---                          |:---                       |:---                     |:---                      |:---                        |
+| *polygons*                   |                           |                         |                          |                            |
+|[`ngon`](@ref)                |[`polysmooth`](@ref)       |[`poly`](@ref)           |[`isinside`](@ref)        |[`simplify`](@ref)          |
+|[`ngonside`](@ref)            |[`polytopath`](@ref)       |[`prettypoly`](@ref)     |[`polyperimeter`](@ref)   |[`polysplit`](@ref)         |
+|[`star`](@ref)                |[`polyintersect`](@ref)    |[`polysmooth`](@ref)     |[`polyarea`](@ref)        |[`polyportion`](@ref)       |
+|[`polycross`](@ref)           |                           |                         |[`polycentroid`](@ref)    |[`polyremainder`](@ref)     |
+|[`offsetpoly`](@ref)          |                           |                         |[`BoundingBox`](@ref)     |[`polysortbyangle`](@ref)   |
+|[`hypotrochoid`](@ref)        |                           |                         |[`ispolyclockwise`](@ref) |[`polysortbydistance`](@ref)|
+|[`epitrochoid`](@ref)         |                           |                         |[`ispolyconvex`](@ref)    |[`polyclip`](@ref)          |
+|[`polyrotate!`](@ref)         |                           |                         |[`ispointonpoly`](@ref)   |[`polymove!`](@ref)         |
+|[`polyfit`](@ref)             |                           |                         |[`polysidelengths`](@ref) |[`polyscale!`](@ref)        |
+|[`polyhull`](@ref)            |                           |                         |                          |[`polyreflect!`](@ref)      |
+|[`polysuper`](@ref)           |                           |                         |                          |[`polysample`](@ref)        |
+|[`polybspline`](@ref)         |                           |                         |                          |[`polytriangulate`](@ref)   |
+|                              |                           |                         |                          |[`insertvertices!`](@ref)   |
+|                              |                           |                         |                          |[`polymorph`](@ref)         |
+|                              |                           |                         |                          |                            |
+|                              |                           |                         |                          |                            |
+| *paths*                      |                           |                         |                          |                            |
+|[`storepath`](@ref)           |                           |                         |                          |                            |
+|[`getpath`](@ref)             |[`pathtopoly`](@ref)       |[`drawpath`](@ref)       |[`pathlength`](@ref)      |[`pathsample`](@ref)        |
+|[`getpathflat`](@ref)         |                           |                         |                          |                            |
+| *Bezier paths*               |                           |                         |                          |                            |
+|[`makebezierpath`](@ref)      |[`pathtobezierpaths`](@ref)|[`drawbezierpath`](@ref) |                          |[`trimbezier`](@ref)        |
+|[`pathtobezierpaths`](@ref)   |[`bezierpathtopoly`](@ref) |[`brush`](@ref)          |                          |[`splitbezier`](@ref)       |
+|`BezierPath`                  |[`bezierpathtopath`](@ref) |[`bezigon`](@ref)        |                          |                            |
+|`BezierPathSegment`           |                           |                         |                          |                            |
+|[`beziersegmentangles`](@ref) |                           |                         |                          |                            |
 
 ## Regular polygons ("ngons")
 
@@ -1327,9 +1327,9 @@ nothing # hide
     rather than open, ie whether that last segment joining
     the end point to the first is used for calculations.
 
-### Polygon side lengths
+### Polygon sides
 
-`polydistances` returns an array of the accumulated side lengths of a polygon.
+`polydistances` returns an array of the accumulated side lengths of a polygon. `polysidelengths()` returns an array of the side lengths without summing them.
 
 ```julia-repl
 julia> p = ngon(O, 100, 7, 0, vertices=true);
@@ -1343,9 +1343,22 @@ julia> polydistances(p)
  433.8837391175581
  520.6604869410697
  607.4372347645814
+
+julia> polysidelengths(p)
+7-element Vector{Float64}:
+ 86.77674782351163
+ 86.77674782351163
+ 86.77674782351161
+ 86.77674782351161
+ 86.77674782351163
+ 86.77674782351161
+ 86.77674782351166
+
+julia> sum(polysidelengths(p))
+607.4372347645814
 ```
 
-It's used by [`polyportion`](@ref) and [`polyremainder`](@ref), and you can pre-calculate and pass them to these functions via keyword arguments for performance. By default the result includes the final closing segment (`closed=true`).
+`polydistances()` is used by [`polyportion`](@ref) and [`polyremainder`](@ref), and you can pre-calculate and pass them to these functions via keyword arguments for performance. By default the result includes the final closing segment (`closed=true`).
 
 These functions also make use of the [`nearestindex`](@ref), which returns a tuple of: the index of the nearest value in an array of distances to a given value; and the excess value.
 

diff --git a/docs/src/howto/simplegraphics.md b/docs/src/howto/simplegraphics.md
@@ -8,9 +8,9 @@ DocTestSetup = quote
 In Luxor, there are different ways of working with graphical
 items:
 
-- Draw them immediately. Create lines and curves to build a **path** on the drawing. When you paint the path, the graphics are ‘fixed’, and you move on to the next.
+- Draw them immediately. Add points and control points defining curves to build a **path** on the drawing. When you paint the path, the graphics are drawn, and ‘fixed’, and you move on to the next.
 
-- Construct arrays of points - **polygons** - which you can draw at some later point. Watch out for a `vertices=true` option, which returns coordinate data rather than adding shapes to the current path.
+- Construct arrays of points - **polygons** - which you can draw at some later stage. Watch out for a `vertices=true` option, which returns coordinate data rather than adding shapes to the current path. Polygons are copied to paths when they're drawn.
 
 - You can combine these two approaches: create a path from lines and curves (and jumps), then store the path, ready for drawing later on.
 
@@ -155,7 +155,7 @@ The [`squircle`](@ref) function makes nicer shapes.
 
 ## Triangles, pentagons, and regular polygons
 
-For regular polygons, pentagons, and so on, see the section on [Polygons and paths](@ref). If you like drawing hexagons, you could also read [Hexagonal grids](@ref).
+For regular polygons, pentagons, and so on, see the section on [Polygons and paths](@ref). If you like drawing hexagons, you could also read [Hexagonal grids](@ref). Eqilateral Triangular grids are also provided ([EquilateralTriangleGrid](@ref)).
 
 ## Circles and ellipses
 
@@ -333,7 +333,7 @@ nothing # hide
 
 ![ellipse in quadrilateral](../assets/figures/ellipseinquad.png)
 
-[`circlepath`](@ref) constructs a circular path from Bézier curves, which allows you to use circles as paths.
+[`circlepath`](@ref) constructs a circular path from Bézier curves.
 
 ```@example
 using Luxor # hide
@@ -547,7 +547,7 @@ These last two functions can return 0, 1, or 2 points (since there are often two
 ```@example
 using Luxor # hide
 @drawsvg begin # hide
-    background("grey10")
+    background("antiquewhite")
     sethue("rebeccapurple")
     setline(3)
     circle(Point(0, 0), 200, :stroke)
@@ -645,7 +645,22 @@ nothing # hide
 
 ![ruling lines clipped to bounding boxes](../assets/figures/rulebbox.png)
 
-Another method of `rule()` draws a line through two points. This example rules lines passing through each pair of adjacent points of the edge of a squircle curve.
+Another method of `rule()` draws a line through two points. 
+
+```@example
+using Luxor, Colors # hide
+
+@drawsvg begin
+    background("antiquewhite")
+    sethue("black")
+    pt1 = Point(-100, -50)
+    pt2 = Point(200, 120)
+    circle.((pt1, pt2), 10, :fill)
+    rule(pt1, pt2)
+end 800 500
+```
+
+This next example rules lines passing through each pair of adjacent points of the edge of a squircle curve.
 
 ```@example
 using Luxor, Colors

diff --git a/docs/src/howto/tables-grids.md b/docs/src/howto/tables-grids.md
@@ -5,7 +5,7 @@ end
 ```
 # Tables and grids
 
-You often want to position graphics at regular locations on the drawing. The positions can be provided by:
+You often want to position graphics at regularly-spaced locations on the drawing. These positions can be provided by:
 
 - `Tiler`: a rectangular grid iterator which you specify by enclosing area, and the number of rows and columns
 - `Partition`: a rectangular grid iterator which you specify by enclosing area, and the width and height of each cell
@@ -14,9 +14,7 @@ You often want to position graphics at regular locations on the drawing. The pos
 
 These are types which act as iterators. Their job is to provide you with centerpoints; you'll probably want to use these in combination with the cell's widths and heights.
 
-There are functions to make hexagonal grids. See [Hexagonal grids](@ref).
-
-There is [EquilateralTriangleGrid](@ref), a grid iterator which generates the vertices for a rectangular grid of equilateral triangles.
+There are also functions to make hexagonal grids ([Hexagonal](@ref) grids and [EquilateralTriangleGrid](@ref) grids.
 
 ## Tiles and partitions