yo

MatrixMania/AGENTS.md

@@ -0,0 +1,8 @@
+## Code Conventions
+- max line length: 88 characters
+- follow PEP 8
+- after creating code: execute "ruff check -fix"
+## Projectstructure
+- sourcecode lies in "src/MatrixMania"
+- test packages, files and functions should start with "test_"
+- test code can be found in "test/test_matrixmania"

MatrixMania/__init__.py

@@ -0,0 +1 @@
+from .compute import matmul, transpose, rot_2d

MatrixMania/compute.py

@@ -0,0 +1,173 @@
+"""
+Modul compute.py
+
+Enthält Funktionen für Matrixoperationen und Rotationen:
+- matmul: Matrixmultiplikation
+- transpose: Transposition einer Matrix
+- rot_2d: 2D-Rotation / Vektorrotation
+- rot_3D: Erzeugung von 3D-Rotationsmatrizen um die x-, y- oder z-Achse
+"""
+
+from collections.abc import Sequence
+import math
+
+Number = float | int
+Matrix = Sequence[Sequence[Number]]
+
+
+def _to_clean_matrix(matrix: Matrix, name: str = "Matrix") -> list[list[Number]]:
+    """Hilfsfunktion: Validiert die Matrixform und wandelt sie in eine Liste von Listen um."""
+    rows = [list(row) for row in matrix]
+    if not rows:
+        raise ValueError(f"{name} darf nicht leer sein.")
+
+    row_len = len(rows[0])
+    if row_len == 0:
+        raise ValueError(f"{name} darf keine leeren Zeilen enthalten.")
+
+    if not all(len(row) == row_len for row in rows):
+        raise ValueError(f"Alle Zeilen von {name} müssen die gleiche Länge haben.")
+
+    return rows
+
+
+def matmul(a: Matrix, b: Matrix) -> list[list[Number]]:
+    """Multipliziert zwei 2D-Matrizen a und b."""
+    a_rows = _to_clean_matrix(a, name="Matrix A")
+    b_rows = _to_clean_matrix(b, name="Matrix B")
+
+    m = len(a_rows)
+    k_a = len(a_rows[0])
+    k_b = len(b_rows)
+    n = len(b_rows[0])
+
+    if k_a != k_b:
+        raise ValueError(
+            f"Inkompatible Dimensionen für Matrizenmultiplikation: "
+            f"({m}x{k_a}) kann nicht mit ({k_b}x{n}) multipliziert werden."
+        )
+
+    result: list[list[Number]] = []
+    for i in range(m):
+        row: list[Number] = []
+        for j in range(n):
+            val = sum(a_rows[i][p] * b_rows[p][j] for p in range(k_a))
+            row.append(val)
+        result.append(row)
+
+    return result
+
+
+def transpose(matrix: Matrix) -> list[list[Number]]:
+    """Transponiert eine 2D-Matrix."""
+    rows = _to_clean_matrix(matrix, name="Matrix")
+    return [list(col) for col in zip(*rows)]
+
+
+def rot_2d(matrix_or_vec: Sequence[Number] | Matrix, angle_rad: float | None = None) -> list[Number] | list[
+    list[Number]]:
+    """Rotiert entweder einen 2D-Vektor um angle_rad oder eine Matrix um 90 Grad."""
+    # Falls als 2D-Vektor aufgerufen: rot_2d([x, y], angle_rad)
+    if angle_rad is not None:
+        if len(matrix_or_vec) != 2:
+            raise ValueError("rot_2d für Vektoren erwartet genau 2 Elemente [x, y].")
+        x, y = matrix_or_vec[0], matrix_or_vec[1]
+        cos_a = math.cos(angle_rad)
+        sin_a = math.sin(angle_rad)
+        return [x * cos_a - y * sin_a, x * sin_a + y * cos_a]
+
+    # Falls als Matrix aufgerufen: rot_2d(matrix)
+    rows = _to_clean_matrix(matrix_or_vec, name="Matrix")
+    return [list(col) for col in zip(*rows[::-1])]
+
+
+def rot_3d(angle: float, axis: str) -> list[list[float]]:
+    """Erzeugt eine 3D-Rotationsmatrix für die Rotation um eine gegebene Achse.
+
+    Formeln der Rotationsmatrizen:
+    ------------------------------
+    Rotation um die x-Achse:
+        R_x(θ) = [
+            [1,          0,           0],
+            [0,  cos(θ), -sin(θ)],
+            [0,  sin(θ),  cos(θ)]
+        ]
+
+    Rotation um die y-Achse:
+        R_y(θ) = [
+            [ cos(θ), 0, sin(θ)],
+            [      0, 1,      0],
+            [-sin(θ), 0, cos(θ)]
+        ]
+
+    Rotation um die z-Achse:
+        R_z(θ) = [
+            [cos(θ), -sin(θ), 0],
+            [sin(θ),  cos(θ), 0],
+            [     0,       0, 1]
+        ]
+
+    Parameters
+    ----------
+    angle : float
+        Rotationswinkel θ im Bogenmaß (Radiant).
+    axis : str
+        Rotationsachse; gültige Werte sind 'x', 'y' oder 'z'.
+
+    Returns
+    -------
+    list[list[float]]
+        Die 3x3-Rotationsmatrix als Liste von Listen.
+
+    Raises
+    ------
+    ValueError
+        Wenn ein ungültiger Achsenbezeichner übergeben wird.
+    """
+    c = math.cos(angle)
+    s = math.sin(angle)
+    axis_norm = axis.strip().lower()
+
+    if axis_norm == "x":
+        return [
+            [1.0, 0.0, 0.0],
+            [0.0, c, -s],
+            [0.0, s, c],
+        ]
+    elif axis_norm == "y":
+        return [
+            [c, 0.0, s],
+            [0.0, 1.0, 0.0],
+            [-s, 0.0, c],
+        ]
+    elif axis_norm == "z":
+        return [
+            [c, -s, 0.0],
+            [s, c, 0.0],
+            [0.0, 0.0, 1.0],
+        ]
+    else:
+        raise ValueError(f"Ungültige Achse '{axis}'. Gültige Werte sind 'x', 'y' oder 'z'.")
+
+def project_ortho(
+    point: tuple[float, float, float], scale: float = 1
+) -> tuple[float, float]:
+    """Projiziert einen 3D-Punkt orthogonal auf eine 2D-Ebene und skaliert ihn optional.
+
+    Die z-Koordinate wird ignoriert. Die verbleibenden x- und y-Koordinaten
+    werden mit dem Skalierungsfaktor multipliziert.
+
+    Parameters
+    ----------
+    point : tuple[float, float, float]
+        Die 3D-Koordinaten (x, y, z).
+    scale : float, default=1
+        Der Skalierungsfaktor.
+
+    Returns
+    -------
+    tuple[float, float]
+        Die projizierten und skalierten 2D-Koordinaten (x * scale, y * scale).
+    """
+    x, y, _ = point
+    return (float(x * scale), float(y * scale))

install_dependencies.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Installiert die Abhängigkeiten aus pyproject.toml in die aktuelle Python-Umgebung.
+
+Ersatz für "Install requirements" aus PyCharm, wenn das Projekt eine pyproject.toml
+statt einer requirements.txt hat. Kein Build, keine besondere Projektstruktur nötig,
+nur Standardbibliothek (Python >= 3.11).
+
+Benutzung:
+  In PyCharm: Rechtsklick auf diese Datei -> Run 'install_dependencies'
+  Im Terminal (venv aktiv): python install_dependencies.py
+
+Ohne Parameter wird ALLES installiert:
+  [project].dependencies + alle [project.optional-dependencies] + alle [dependency-groups]
+
+Abweichendes Verhalten:
+  python install_dependencies.py --extra dev        nur Basis + Extra "dev"
+  python install_dependencies.py --group test       nur Basis + Gruppe "test"
+  python install_dependencies.py --no-main --group dev
+  python install_dependencies.py --list             nur anzeigen, nichts installieren
+  python install_dependencies.py --write            requirements.txt schreiben statt installieren
+  python install_dependencies.py --write -o reqs.txt
+"""
+from __future__ import annotations
+
+import sys
+
+if sys.version_info < (3, 11):
+    sys.exit("Dieses Skript braucht Python 3.11 oder neuer (tomllib). "
+             f"Aktuell: {sys.version.split()[0]}")
+
+import argparse
+import subprocess
+import tempfile
+import tomllib
+from pathlib import Path
+
+PROJECT_DIR = Path(__file__).resolve().parent
+
+
+def resolve_group(groups: dict, name: str, seen: set[str] | None = None) -> list[str]:
+    """Löst eine Dependency-Group inkl. {include-group = "..."} rekursiv auf."""
+    seen = set() if seen is None else seen
+    if name in seen:
+        raise ValueError(f"Zyklische include-group: {name}")
+    if name not in groups:
+        raise KeyError(f"Dependency-Group '{name}' nicht gefunden")
+    seen.add(name)
+    result: list[str] = []
+    for entry in groups[name]:
+        if isinstance(entry, str):
+            result.append(entry)
+        elif isinstance(entry, dict) and "include-group" in entry:
+            result.extend(resolve_group(groups, entry["include-group"], seen))
+    return result
+
+
+def collect(data: dict, extras: list[str], groups: list[str], no_main: bool) -> list[str]:
+    project = data.get("project", {})
+    optional = project.get("optional-dependencies", {})
+    dep_groups = data.get("dependency-groups", {})
+    deps: list[str] = []
+
+    if not no_main:
+        deps.extend(project.get("dependencies", []))
+    for extra in extras:
+        if extra not in optional:
+            raise KeyError(f"Optional-Dependency '{extra}' nicht gefunden")
+        deps.extend(optional[extra])
+    for group in groups:
+        deps.extend(resolve_group(dep_groups, group))
+
+    # Duplikate entfernen, Reihenfolge behalten
+    return list(dict.fromkeys(d.strip() for d in deps if d.strip()))
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-p", "--pyproject", type=Path, default=PROJECT_DIR / "pyproject.toml",
+                   help="Pfad zur pyproject.toml (Standard: neben diesem Skript)")
+    p.add_argument("--extra", action="append", default=None,
+                   help="nur diese optional-dependencies (mehrfach möglich)")
+    p.add_argument("--group", action="append", default=None,
+                   help="nur diese dependency-groups (mehrfach möglich)")
+    p.add_argument("--no-main", action="store_true", help="[project].dependencies weglassen")
+    p.add_argument("--list", action="store_true", help="Abhängigkeiten nur anzeigen")
+    p.add_argument("--write", action="store_true", help="requirements-Datei schreiben statt installieren")
+    p.add_argument("-o", "--output", type=Path, default=PROJECT_DIR / "requirements.txt",
+                   help="Zieldatei für --write")
+    args = p.parse_args()
+
+    if not args.pyproject.exists():
+        print(f"{args.pyproject} nicht gefunden", file=sys.stderr)
+        return 1
+    data = tomllib.loads(args.pyproject.read_text(encoding="utf-8"))
+    all_extras = list(data.get("project", {}).get("optional-dependencies", {}))
+    all_groups = list(data.get("dependency-groups", {}))
+
+    # Ohne --extra/--group: alles. Mit einem davon: nur das Gewählte.
+    selective = args.extra is not None or args.group is not None
+    extras = (args.extra or []) if selective else all_extras
+    groups = (args.group or []) if selective else all_groups
+
+    try:
+        deps = collect(data, extras, groups, args.no_main)
+    except (KeyError, ValueError) as e:
+        print(f"Fehler: {e.args[0]}", file=sys.stderr)
+        print(f"  Vorhandene --extra: {', '.join(all_extras) or '(keine)'}", file=sys.stderr)
+        print(f"  Vorhandene --group: {', '.join(all_groups) or '(keine)'}", file=sys.stderr)
+        return 1
+
+    parts = ([] if args.no_main else ["Basis"]) + [f"extra:{e}" for e in extras] + [f"group:{g}" for g in groups]
+    print(f"Auswahl: {', '.join(parts) or '(nichts)'}")
+
+    if args.list:
+        print("\n".join(deps) or "(keine Abhängigkeiten)")
+        return 0
+
+    content = f"# Automatisch erzeugt aus {args.pyproject.name} – nicht von Hand bearbeiten\n" + "\n".join(deps) + "\n"
+
+    if args.write:
+        args.output.write_text(content, encoding="utf-8")
+        print(f"{len(deps)} Abhängigkeiten -> {args.output}")
+        return 0
+
+    if not deps:
+        print("Keine Abhängigkeiten gefunden – nichts zu tun.")
+        return 0
+
+    if sys.prefix == sys.base_prefix:
+        print("WARNUNG: Es ist kein virtuelles Environment aktiv – es wird in die globale "
+              f"Python-Installation installiert:\n  {sys.prefix}", file=sys.stderr)
+        if sys.stdin.isatty() and input("Trotzdem fortfahren? [j/N] ").strip().lower() not in ("j", "ja", "y", "yes"):
+            return 1
+
+    with tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False, encoding="utf-8") as tmp:
+        tmp.write(content)
+        tmp_path = Path(tmp.name)
+    try:
+        print(f"Installiere {len(deps)} Abhängigkeiten in {sys.prefix}\n")
+        return subprocess.call([sys.executable, "-m", "pip", "install", "-r", str(tmp_path)])
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyproject.toml

@@ -0,0 +1,4 @@
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "pytest-cov"]
+[tool.pytest.ini_options]
+pythonpath = "src"

test/test_matrixmania/test_rot.py

@@ -0,0 +1,88 @@
+import math
+import pytest
+from src.MatrixMania.compute import rot_2d, rot_3d
+
+
+# --- Tests für rot_2d ---
+
+def test_rot_2d_vector_valid():
+    # 90° Drehung von [1, 0] um den Ursprung -> [0, 1]
+    res = rot_2d([1.0, 0.0], math.pi / 2)
+    assert math.isclose(res[0], 0.0, abs_tol=1e-9)
+    assert math.isclose(res[1], 1.0, abs_tol=1e-9)
+
+
+def test_rot_2d_matrix_valid():
+    # 90° Drehung im Uhrzeigersinn
+    m = [[1, 2], [3, 4]]
+    assert rot_2d(m) == [[3, 1], [4, 2]]
+
+
+def test_rot_2d_invalid_vector():
+    # Vektor mit ungültiger Länge muss ValueError werfen
+    with pytest.raises(ValueError):
+        rot_2d([1.0, 2.0, 3.0], math.pi)
+
+
+# --- Tests für rot_3D ---
+
+def test_rot_3d_identity():
+    # Bei Winkel 0 müssen alle Achsen die Einheitsmatrix liefern
+    eye = [
+        [1.0, 0.0, 0.0],
+        [0.0, 1.0, 0.0],
+        [0.0, 0.0, 1.0],
+    ]
+    for axis in ["x", "y", "z"]:
+        res = rot_3d(0.0, axis)
+        for r in range(3):
+            for c in range(3):
+                assert math.isclose(res[r][c], eye[r][c], abs_tol=1e-9)
+
+
+def test_rot_3d_x_axis():
+    # 90° um x-Achse
+    res = rot_3d(math.pi / 2, "x")
+    expected = [
+        [1.0, 0.0, 0.0],
+        [0.0, 0.0, -1.0],
+        [0.0, 1.0, 0.0],
+    ]
+    for r in range(3):
+        for c in range(3):
+            assert math.isclose(res[r][c], expected[r][c], abs_tol=1e-9)
+
+
+def test_rot_3d_y_axis():
+    # 90° um y-Achse
+    res = rot_3d(math.pi / 2, "y")
+    expected = [
+        [0.0, 0.0, 1.0],
+        [0.0, 1.0, 0.0],
+        [-1.0, 0.0, 0.0],
+    ]
+    for r in range(3):
+        for c in range(3):
+            assert math.isclose(res[r][c], expected[r][c], abs_tol=1e-9)
+
+
+def test_rot_3d_z_axis():
+    # 90° um z-Achse
+    res = rot_3d(math.pi / 2, "z")
+    expected = [
+        [0.0, -1.0, 0.0],
+        [1.0, 0.0, 0.0],
+        [0.0, 0.0, 1.0],
+    ]
+    for r in range(3):
+        for c in range(3):
+            assert math.isclose(res[r][c], expected[r][c], abs_tol=1e-9)
+
+
+def test_rot_3d_invalid_axis():
+    # Ungültige Achsenbezeichnung muss ValueError werfen
+    with pytest.raises(ValueError):
+        rot_3d(math.pi / 2, "w")
+
+    with pytest.raises(ValueError):
+        rot_3d(math.pi / 2, "1")