From 9fd17d5766559c5089a41fe3ed465964693e0d32 Mon Sep 17 00:00:00 2001
From: Jacob Peck <gatesphere@gmail.com>
Date: Tue, 9 Apr 2024 03:46:41 -0400
Subject: [PATCH] Add 'lineshuffle' command (#715)

* Add 'lineshuffle' command and d.

* Add lineshuffle PR# to CHANGELOG.md

* Revert docs/CHANGELOG.md to a symlink, remove useless lineshuffle test.

* Simplified doc string and code

---------

Co-authored-by: Antoine Beyeler <abeyeler@ab-ware.com>
---
 CHANGELOG.md            |  1 +
 docs/conf.py            |  1 -
 docs/reference.rst      |  4 ++++
 tests/test_commands.py  |  1 +
 vpype_cli/operations.py | 16 ++++++++++++++++
 5 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6806b92f..70898614 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ Release date: UNRELEASED
 ### New features and improvements
 
 * Added a `--orientation` option to the `pagerotate` command to conditionally rotate the page to a target orientation (thanks to @gatesphere) (#705)
+* Added a `lineshuffle` command to randomize the plotting order of lines in the current geometry (thanks to @gatesphere) (#715)
 
 ### Bug fixes
 
diff --git a/docs/conf.py b/docs/conf.py
index a64feffe..8ab2194b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -4,7 +4,6 @@
 
 import vpype as vp
 
-
 project = "vpype"
 # noinspection PyShadowingBuiltins
 copyright = "2020-2022, Antoine Beyeler"
diff --git a/docs/reference.rst b/docs/reference.rst
index d213c745..c360ca11 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -87,6 +87,10 @@ CLI reference
 .. click:: vpype_cli:linemerge
    :prog: linemerge
 
+.. _cmd_lineshuffle:
+.. click:: vpype_cli:lineshuffle
+   :prog: lineshuffle
+
 .. _cmd_linesimplify:
 .. click:: vpype_cli:linesimplify
    :prog: linesimplify
diff --git a/tests/test_commands.py b/tests/test_commands.py
index 414372d5..4fa7fe13 100644
--- a/tests/test_commands.py
+++ b/tests/test_commands.py
@@ -53,6 +53,7 @@ class Command:
     Command("skew 0 0"),
     Command("translate 0 0"),
     Command("crop 0 0 1 1"),
+    Command("lineshuffle"),
     Command("linesort"),
     Command("linesort --two-opt"),
     Command("random linesort"),  # make sure there is something sort
diff --git a/vpype_cli/operations.py b/vpype_cli/operations.py
index 1ddbade8..cf4075b5 100644
--- a/vpype_cli/operations.py
+++ b/vpype_cli/operations.py
@@ -2,6 +2,7 @@
 
 import logging
 import math
+import random
 from typing import cast
 
 import click
@@ -25,6 +26,7 @@
     "filter_command",
     "layout",
     "linemerge",
+    "lineshuffle",
     "linesimplify",
     "linesort",
     "multipass",
@@ -328,6 +330,20 @@ def linesimplify(lines: vp.LineCollection, tolerance):
     return new_lines
 
 
+@cli.command(group="Operations")
+@layer_processor
+def lineshuffle(lines: vp.LineCollection) -> vp.LineCollection:
+    """Randomizes the line order within layer.
+
+    This command may be useful for testing purposes or spreading out the area in which the pen
+    is drawing over time, for example to let ink dry. It will almost always increase plotting
+    time, sometimes considerably.
+    """
+
+    random.shuffle(lines.lines)
+    return lines
+
+
 @cli.command(group="Operations")
 @click.option(
     "-t",