view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    - `angle_range` (default: 90% of visible cone)

        Total horizontal angular span of the image in degrees.

    - `elev_range` (default: 80% of base elevation)

        Total vertical angular span of the image in degrees.

    - `step` (default 1.0)

        Maximum distance (in drawing units) between consecutive sample points along
        a segment.  Smaller values give smoother distorted curves at the cost of
        more output moves.

# SWIRL METHODS

A _swirl_ (also called _pursuit-curve polygon_) is produced by iteratively
constructing a series of nested polygons where each new vertex lies a fixed
fractional distance along an edge of the enclosing polygon.  The corners of
successive polygons trace discrete approximations to logarithmic spirals.

The role is composed automatically when [Graphics::Penplotter::GcodeXY](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY) is
loaded; no extra `use` statement is required in user code.

See [Graphics::Penplotter::GcodeXY::Swirl](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3ASwirl) for the construction algorithm
and termination conditions.

- swirl(%args)

    Draw a whirl from the given polygon.  Named arguments:

    - `points => \@pts`  (**compulsory**)

        A reference to a flat array of vertex coordinates in alternating X, Y order:
        `[x0,y0, x1,y1, ...]`.  At least 3 vertices are required.  Coordinates are
        in the current drawing units.

    - `d => \@d`  (**compulsory**)

        A reference to an array of _advance percentages_, one per edge (same count as
        vertices).  Each value specifies how far along the corresponding edge the next
        polygon's vertex is placed.  Values are percentages in the range `0`-`100`.
        For example, `20` means 20% of the way along the edge.

        When all values are equal to `50`, consecutive polygons degenerate to straight
        lines (no visible spiral).  Values close to `0` or `100` produce densely
        packed spirals; values close to `50` produce loosely spaced ones.

    - `direction => 0|1`  (optional, default `0`)

        Spiral direction.  `0` (`$SWIRL_CW`) gives a clockwise whirl; `1`
        (`$SWIRL_CCW`) gives a counter-clockwise whirl.

    - `draw => \@bool`  (optional, default all `1`)

        A reference to an array of boolean flags, one per edge, that controls whether
        each edge of every nested polygon is drawn.  Setting some flags to false can
        produce striking visual effects.

    - `iterations => $n`  (optional)

        Draw exactly `$n` nested polygons (not counting the base polygon).  When
        given, this takes precedence over `min_size`.

    - `min_size => $pct`  (optional, default `1.0`)

        Stop iterating once the length of the first edge of the current polygon has
        shrunk to `$pct` percent of the original first-edge length.  Ignored when
        `iterations` is also given.

    Returns `1` on success.  Croaks on invalid input.

## Swirl package variables

- `$Graphics::Penplotter::GcodeXY::Swirl::SWIRL_CW`

    Constant `0` - clockwise direction (the default).

- `$Graphics::Penplotter::GcodeXY::Swirl::SWIRL_CCW`

    Constant `1` - counter-clockwise direction.

# OPTIMIZE

A peephole optimiser applied automatically to the internal segment queue before
gcode generation.  No user-facing API change is needed; the optimiser runs
transparently via `_flushPsegments`.

The optimiser makes a single pass over the `psegments` array, matching named
patterns (tested longest-first) and rewriting or deleting redundant
instructions.  After each match the window is retracted so that newly formed
optimisable sequences are not missed (Tanenbaum-style peephole).

The following object attributes configure its behaviour:

- `optimize`

    Set to `0` to disable the optimiser entirely.  Default is `1`.

- `check`

    When set, prints the number of instructions removed to STDOUT.

- `opt_debug`

    When set, prints a per-instruction trace to STDOUT.

See [Graphics::Penplotter::GcodeXY::Optimize](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AOptimize) for a full description of all
recognised patterns.

# BUGS AND LIMITATIONS

As noted above, the SVG specification (900 pages) is only partially implemented,
and just one layer can be used. I suspect that diagnostics about pen travel distance
may not always be correct. Layering is not supported officially, but can be simulated.

# SEE ALSO

[Graphics::Penplotter::GcodeXY::Geometry2D](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AGeometry2D),
[Graphics::Penplotter::GcodeXY::Geometry3D](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AGeometry3D),
[Graphics::Penplotter::GcodeXY::Postscript](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3APostscript),
[Graphics::Penplotter::GcodeXY::SVG](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3ASVG),
[Graphics::Penplotter::GcodeXY::Split](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3ASplit),
[Graphics::Penplotter::GcodeXY::Hatch](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AHatch),
[Graphics::Penplotter::GcodeXY::Font](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AFont),
[Graphics::Penplotter::GcodeXY::Vpype](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AVpype),
[Graphics::Penplotter::GcodeXY::Optimize](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AOptimize),
[Graphics::Penplotter::GcodeXY::Anamorphic](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3AAnamorphic),
[Graphics::Penplotter::GcodeXY::Swirl](https://metacpan.org/pod/Graphics%3A%3APenplotter%3A%3AGcodeXY%3A%3ASwirl)