From 4e9886dba8427a85305b02610a6b8a1e8cc0dd98 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Wed, 4 Nov 2020 08:41:06 +0100
Subject: [PATCH] api/geometry: add new module

This module will contain mathematical tools to deal with geometry and motion of robots. This includes a Matrix type for common matrix operations.
---
 doc/api/geometry.rst | 13 ++++++++++++
 doc/api/index.rst    |  1 +
 pybricks/geometry.py | 47 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 61 insertions(+)
 create mode 100644 doc/api/geometry.rst
 create mode 100644 pybricks/geometry.py

diff --git a/doc/api/geometry.rst b/doc/api/geometry.rst
new file mode 100644
index 0000000..856a934
--- /dev/null
+++ b/doc/api/geometry.rst
@@ -0,0 +1,13 @@
+:mod:`geometry <pybricks.geometry>` -- Geometry and algebra
+============================================================
+
+.. module:: pybricks.geometry
+
+.. autoclass:: pybricks.geometry.Matrix
+    :no-members:
+
+    .. autoattribute:: pybricks.geometry::Matrix.T
+
+    .. autoattribute:: pybricks.geometry::Matrix.shape
+
+.. autofunction:: pybricks.geometry.vector
diff --git a/doc/api/index.rst b/doc/api/index.rst
index 71bb086..545c58b 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -82,6 +82,7 @@ findings on our `support page`_ so we can make Pybricks even better.
    robotics
    media
    messaging
+   geometry
 
 .. toctree::
    :maxdepth: 1
diff --git a/pybricks/geometry.py b/pybricks/geometry.py
new file mode 100644
index 0000000..1a1a837
--- /dev/null
+++ b/pybricks/geometry.py
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2018-2020 The Pybricks Authors
+
+"""Core linear algebra functionality for orientation sensors and robotics."""
+
+
+class Matrix:
+    """Mathematical representation of a matrix. It supports common operations
+    such as matrix addition (``+``), subtraction (``-``),
+    and multiplication (``*``). A :class:`.Matrix` object is immutable."""
+
+    def __init__(self, rows):
+        """
+
+        Arguments:
+            rows (list): List of rows. Each row is itself a list of numbers.
+
+        """
+
+    @property
+    def T(self):
+        """Returns a new :class:`.Matrix` that is the transpose of the
+        original."""
+        pass
+
+    @property
+    def shape(self):
+        """Returns a tuple (``m``, ``n``),
+        where ``m`` is the number of rows and ``n`` is the number of columns.
+        """
+        pass
+
+
+def vector(x, y, z=None):
+    """Convenience function to create a :class:`.Matrix` with the
+    shape (``3``, ``1``) or (``2``, ``1``).
+
+    Arguments:
+        x (float): x-coordinate of the vector.
+        y (float): y-coordinate of the vector.
+        z (float): z-coordinate of the vector (optional).
+
+
+    Returns:
+            Matrix: A matrix with the shape of a column vector.
+    """
+    pass