pybricks.geometry: Drop module.

laurensvalk · laurensvalk · commit 9cde749e8a49 · 2023-04-21T13:33:19.000+02:00
See pybricks/pybricks-micropython#160
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,13 @@
 ### Changed
 - Change implementation status of `IMU.heading` and `IMU.reset_heading`. They
   are now implemented, with some limitations as noted in a note box.
+- Moved `Matrix` and `vector` from `pybricks.geometry` to `pybricks.tools`.
+- Moved `Axis` from `pybricks.geometry` to `pybricks.parameters`.
+
+### Removed
+- Removed `pybricks.geometry` module.
+
+### Changed
 
 ## 3.2.0 - 2022-12-20
 
diff --git a/doc/common/extensions/requirements-static.py b/doc/common/extensions/requirements-static.py
@@ -10,7 +10,6 @@
 
 # Medium feature set.
 FEATURES_MEDIUM = FEATURES_SMALL | {
-    "pybricks-geometry",
     "pybricks-common-control",
     "pybricks-iodevices",
     "stm32-extra",
diff --git a/doc/main/geometry.rst b/doc/main/geometry.rst
diff --git a/doc/main/index.rst b/doc/main/index.rst
@@ -60,7 +60,6 @@ above to reveal this menu.
    parameters/index
    tools/index
    robotics
-   geometry
    signaltypes
 
 .. toctree::
diff --git a/doc/main/parameters/axis.rst b/doc/main/parameters/axis.rst
@@ -0,0 +1,7 @@
+.. pybricks-requirements:: stm32-float
+
+Axis
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: pybricks.parameters.Axis
+    :no-members:
diff --git a/doc/main/parameters/index.rst b/doc/main/parameters/index.rst
@@ -10,6 +10,7 @@
    :maxdepth: 1
    :hidden:
 
+   axis
    button
    color
    direction
@@ -18,6 +19,8 @@
    side
    stop
 
+.. pybricks-classlink:: Axis
+
 .. pybricks-classlink:: Button
 
 .. pybricks-classlink:: Color
diff --git a/doc/main/signaltypes.rst b/doc/main/signaltypes.rst
@@ -260,3 +260,36 @@ Fahrenheit (°F) or Kelvin (K), you can use the following conversion formulas:
 hue: deg
 --------------
 Hue of a color (0-359 degrees).
+
+.. _robotframe:
+
+Reference frames
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Pybricks module and this documentation use the following conventions:
+
+- X: Positive means forward. Negative means backward.
+- Y: Positive means to the left. Negative means to the right.
+- Z: Positive means upward. Negative means downward.
+
+To make sure that all hub measurements (such as acceleration) have the correct
+value and sign, you can specify how the hub is mounted in your creation. This
+adjust the measurements so that it is easy to see how your *robot* is moving,
+rather than how the *hub* is moving.
+
+For example, the hub may be mounted upside down in your design. If you
+configure the settings as shown in :numref:`fig_imuexamples`, the hub
+measurements will be adjusted accordingly. This way, a positive acceleration
+value in the X direction means that your *robot* accelerates forward, even
+though the *hub* accelerates backward.
+
+.. _fig_imuexamples:
+
+.. figure:: ../main/diagrams/imuexamples.png
+   :width: 100 %
+
+   How to configure the ``top_side`` and ``front_side`` settings for three
+   different robot designs. The same technique can be applied to other hubs
+   and other creations, by noting which way the top and
+   front :class:`Side <Side>` of the hub are pointing. The example
+   on the left is the default configuration.
diff --git a/doc/main/tools/index.rst b/doc/main/tools/index.rst
@@ -19,3 +19,15 @@
 
     .. automethod:: pybricks.tools.StopWatch.reset
 
+.. pybricks-requirements:: stm32-float
+
+.. autoclass:: pybricks.tools.Matrix
+    :no-members:
+
+    .. autoattribute:: pybricks.tools::Matrix.T
+
+    .. autoattribute:: pybricks.tools::Matrix.shape
+
+.. pybricks-requirements:: stm32-float
+
+.. autofunction:: pybricks.tools.vector
diff --git a/examples/pup/hub_common/imu_read_scalar.py b/examples/pup/hub_common/imu_read_scalar.py
@@ -1,7 +1,7 @@
 # ThisHub = TechnicHub PrimeHub EssentialHub
 from pybricks.hubs import ThisHub
 from pybricks.tools import wait
-from pybricks.geometry import Axis
+from pybricks.parameters import Axis
 
 # Initialize the hub.
 hub = ThisHub()
diff --git a/examples/pup/hub_common/imu_tilt_blast.py b/examples/pup/hub_common/imu_tilt_blast.py
@@ -1,7 +1,7 @@
 # ThisHub = TechnicHub PrimeHub EssentialHub
 from pybricks.hubs import ThisHub
 from pybricks.tools import wait
-from pybricks.geometry import Axis
+from pybricks.parameters import Axis
 
 # Initialize the hub. In this case, specify that the hub is mounted with the
 # top side facing forward and the front side facing to the right.
diff --git a/examples/pup/hub_primehub/display_matrix.py b/examples/pup/hub_primehub/display_matrix.py
@@ -1,6 +1,5 @@
 from pybricks.hubs import PrimeHub
-from pybricks.tools import wait
-from pybricks.geometry import Matrix
+from pybricks.tools import wait, Matrix
 
 # Initialize the hub.
 hub = PrimeHub()
diff --git a/jedi/src/pybricks_jedi/__init__.py b/jedi/src/pybricks_jedi/__init__.py
@@ -13,7 +13,6 @@
 PYBRICKS_CODE_PACKAGES = {
     "micropython",
     "pybricks",
-    "pybricks.geometry",
     "pybricks.hubs",
     "pybricks.iodevices",
     "pybricks.parameters",
@@ -489,7 +488,6 @@ def initialize():
         "pybricks._common",
         "pybricks.ev3dev",
         "pybricks.ev3dev.speaker",
-        "pybricks.geometry",
         "pybricks.hubs",
         "pybricks.iodevices",
         "pybricks.parameters",
diff --git a/jedi/tests/test_complete_import.py b/jedi/tests/test_complete_import.py
@@ -59,7 +59,6 @@ def test_from_pybricks_import():
     code = "from pybricks import "
     completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
     assert [c["insertText"] for c in completions] == [
-        "geometry",
         "hubs",
         "iodevices",
         "parameters",
@@ -74,7 +73,6 @@ def test_from_pybricks_dot():
     code = "from pybricks."
     completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
     assert [c["insertText"] for c in completions] == [
-        "geometry",
         "hubs",
         "iodevices",
         "parameters",
@@ -84,16 +82,6 @@ def test_from_pybricks_dot():
     ]
 
 
-def test_from_pybricks_geometry_import():
-    code = "from pybricks.geometry import "
-    completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
-    assert [c["insertText"] for c in completions] == [
-        "Axis",
-        "Matrix",
-        "vector",
-    ]
-
-
 def test_from_pybricks_hubs_import():
     code = "from pybricks.hubs import "
     completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
@@ -127,6 +115,7 @@ def test_from_pybricks_parameters_import():
     code = "from pybricks.parameters import "
     completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
     assert [c["insertText"] for c in completions] == [
+        "Axis",
         "Button",
         "Color",
         "Direction",
@@ -167,7 +156,9 @@ def test_from_pybricks_tools_import():
     completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
     assert [c["insertText"] for c in completions] == [
         "DataLog",
+        "Matrix",
         "StopWatch",
+        "vector",
         "wait",
     ]
 
diff --git a/jedi/tests/test_get_signature.py b/jedi/tests/test_get_signature.py
@@ -31,7 +31,7 @@ def _get_function_signature(module: str, function: str) -> SignatureHelp:
 FUNCTION_PARAMS = [
     pytest.param("pybricks.tools", "wait", [(["time: Number"], "None")]),
     pytest.param(
-        "pybricks.geometry",
+        "pybricks.tools",
         "vector",
         [
             (["x: float", "y: float"], "Matrix"),
@@ -152,7 +152,7 @@ def _get_constructor_signature(module: str, type: str) -> SignatureHelp:
         ],
     ),
     pytest.param(
-        "pybricks.geometry",
+        "pybricks.tools",
         "Matrix",
         [["rows: Sequence[Sequence[float]]"]],
     ),
diff --git a/src/pybricks/_common.py b/src/pybricks/_common.py
@@ -8,8 +8,8 @@
 
 from typing import Union, Iterable, overload, Optional, Tuple, Collection, TYPE_CHECKING
 
-from .geometry import Matrix, Axis
-from .parameters import Direction, Stop, Button, Port, Color, Side
+from .tools import Matrix
+from .parameters import Axis, Direction, Stop, Button, Port, Color, Side
 
 if TYPE_CHECKING:
     from .parameters import Number
@@ -794,7 +794,7 @@ def animate(self, matrices: Collection[Matrix], interval: Number) -> None:
 
         Arguments:
             matrices (iter): Sequence of
-                :class:`Matrix <pybricks.geometry.Matrix>` of intensities.
+                :class:`Matrix <pybricks.tools.Matrix>` of intensities.
             interval (Number, ms): Time to display each image in the list.
         """
 
diff --git a/src/pybricks/geometry.py b/src/pybricks/geometry.py
diff --git a/src/pybricks/hubs.py b/src/pybricks/hubs.py
diff --git a/src/pybricks/parameters.py b/src/pybricks/parameters.py
diff --git a/src/pybricks/tools.py b/src/pybricks/tools.py
