minigeo 0.5.7__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. minigeo-0.5.7/.github/workflows/publish.yml +50 -0
  2. minigeo-0.5.7/.github/workflows/python-app.yml +48 -0
  3. minigeo-0.5.7/.gitignore +59 -0
  4. minigeo-0.5.7/.readthedocs.yml +17 -0
  5. minigeo-0.5.7/AUTHORS.rst +5 -0
  6. minigeo-0.5.7/CHANGELOG.rst +43 -0
  7. minigeo-0.5.7/CONTRIBUTING.rst +13 -0
  8. minigeo-0.5.7/LICENSE +21 -0
  9. minigeo-0.5.7/PKG-INFO +345 -0
  10. minigeo-0.5.7/PLAN.md +93 -0
  11. minigeo-0.5.7/README.rst +306 -0
  12. minigeo-0.5.7/binder/requirements.txt +4 -0
  13. minigeo-0.5.7/binder/runtime.txt +1 -0
  14. minigeo-0.5.7/docs/Makefile +29 -0
  15. minigeo-0.5.7/docs/_ext/minigeo_manual.py +294 -0
  16. minigeo-0.5.7/docs/_static/.gitignore +1 -0
  17. minigeo-0.5.7/docs/_static/minigeo-manual.css +37 -0
  18. minigeo-0.5.7/docs/api.rst +141 -0
  19. minigeo-0.5.7/docs/authors.rst +2 -0
  20. minigeo-0.5.7/docs/changelog.rst +2 -0
  21. minigeo-0.5.7/docs/conf.py +36 -0
  22. minigeo-0.5.7/docs/contributing.rst +1 -0
  23. minigeo-0.5.7/docs/index.rst +18 -0
  24. minigeo-0.5.7/docs/license.rst +7 -0
  25. minigeo-0.5.7/docs/manual/anchors.rst +123 -0
  26. minigeo-0.5.7/docs/manual/backends.rst +168 -0
  27. minigeo-0.5.7/docs/manual/first-steps.rst +112 -0
  28. minigeo-0.5.7/docs/manual/frames.rst +105 -0
  29. minigeo-0.5.7/docs/manual/index.rst +34 -0
  30. minigeo-0.5.7/docs/manual/looks.rst +170 -0
  31. minigeo-0.5.7/docs/manual/measuring.rst +144 -0
  32. minigeo-0.5.7/docs/manual/own-axes.rst +72 -0
  33. minigeo-0.5.7/docs/manual/shapes.rst +89 -0
  34. minigeo-0.5.7/docs/manual/styles.rst +105 -0
  35. minigeo-0.5.7/docs/manual/transforms.rst +111 -0
  36. minigeo-0.5.7/docs/manual/view.rst +69 -0
  37. minigeo-0.5.7/docs/readme.rst +2 -0
  38. minigeo-0.5.7/docs/requirements.txt +3 -0
  39. minigeo-0.5.7/examples/Cristallina.ipynb +375 -0
  40. minigeo-0.5.7/examples/animations.ipynb +213 -0
  41. minigeo-0.5.7/examples/diagram.png +0 -0
  42. minigeo-0.5.7/examples/getting_started.ipynb +793 -0
  43. minigeo-0.5.7/examples/joints.ipynb +437 -0
  44. minigeo-0.5.7/examples/minigeo.png +0 -0
  45. minigeo-0.5.7/examples/readme_image.py +43 -0
  46. minigeo-0.5.7/examples/table_scene.py +66 -0
  47. minigeo-0.5.7/examples/table_scene.svg +1 -0
  48. minigeo-0.5.7/examples/turning.png +0 -0
  49. minigeo-0.5.7/examples/xyz_stage.py +104 -0
  50. minigeo-0.5.7/examples/xyz_stage.svg +1 -0
  51. minigeo-0.5.7/pyproject.toml +71 -0
  52. minigeo-0.5.7/setup.cfg +4 -0
  53. minigeo-0.5.7/src/minigeo/__init__.py +61 -0
  54. minigeo-0.5.7/src/minigeo/anchors.py +123 -0
  55. minigeo-0.5.7/src/minigeo/backends/__init__.py +7 -0
  56. minigeo-0.5.7/src/minigeo/backends/_fastcast.py +342 -0
  57. minigeo-0.5.7/src/minigeo/backends/matplotlib.py +561 -0
  58. minigeo-0.5.7/src/minigeo/backends/plotly.py +326 -0
  59. minigeo-0.5.7/src/minigeo/backends/raytrace.py +1425 -0
  60. minigeo-0.5.7/src/minigeo/backends/svg.py +227 -0
  61. minigeo-0.5.7/src/minigeo/backends/tikz.py +318 -0
  62. minigeo-0.5.7/src/minigeo/camera.py +77 -0
  63. minigeo-0.5.7/src/minigeo/colors.py +186 -0
  64. minigeo-0.5.7/src/minigeo/depth.py +186 -0
  65. minigeo-0.5.7/src/minigeo/exact.py +120 -0
  66. minigeo-0.5.7/src/minigeo/flat.py +149 -0
  67. minigeo-0.5.7/src/minigeo/frames.py +386 -0
  68. minigeo-0.5.7/src/minigeo/geometry/__init__.py +89 -0
  69. minigeo-0.5.7/src/minigeo/geometry/annotations.py +250 -0
  70. minigeo-0.5.7/src/minigeo/geometry/base.py +99 -0
  71. minigeo-0.5.7/src/minigeo/geometry/legacy.py +71 -0
  72. minigeo-0.5.7/src/minigeo/geometry/plane.py +113 -0
  73. minigeo-0.5.7/src/minigeo/geometry/primitives.py +273 -0
  74. minigeo-0.5.7/src/minigeo/geometry/shape.py +244 -0
  75. minigeo-0.5.7/src/minigeo/geometry/shapes.py +384 -0
  76. minigeo-0.5.7/src/minigeo/groups.py +123 -0
  77. minigeo-0.5.7/src/minigeo/measure.py +222 -0
  78. minigeo-0.5.7/src/minigeo/render.py +172 -0
  79. minigeo-0.5.7/src/minigeo/scene.py +444 -0
  80. minigeo-0.5.7/src/minigeo/style.py +107 -0
  81. minigeo-0.5.7/src/minigeo/transform.py +325 -0
  82. minigeo-0.5.7/src/minigeo.egg-info/PKG-INFO +345 -0
  83. minigeo-0.5.7/src/minigeo.egg-info/SOURCES.txt +110 -0
  84. minigeo-0.5.7/src/minigeo.egg-info/dependency_links.txt +1 -0
  85. minigeo-0.5.7/src/minigeo.egg-info/requires.txt +32 -0
  86. minigeo-0.5.7/src/minigeo.egg-info/scm_file_list.json +107 -0
  87. minigeo-0.5.7/src/minigeo.egg-info/scm_version.json +8 -0
  88. minigeo-0.5.7/src/minigeo.egg-info/top_level.txt +1 -0
  89. minigeo-0.5.7/tests/test_anchors.py +356 -0
  90. minigeo-0.5.7/tests/test_animation.py +135 -0
  91. minigeo-0.5.7/tests/test_annotations.py +250 -0
  92. minigeo-0.5.7/tests/test_api.py +204 -0
  93. minigeo-0.5.7/tests/test_backend_matplotlib.py +114 -0
  94. minigeo-0.5.7/tests/test_backend_plotly.py +100 -0
  95. minigeo-0.5.7/tests/test_backend_raytrace.py +526 -0
  96. minigeo-0.5.7/tests/test_backend_svg.py +145 -0
  97. minigeo-0.5.7/tests/test_backend_tikz.py +207 -0
  98. minigeo-0.5.7/tests/test_basic_geometry.py +145 -0
  99. minigeo-0.5.7/tests/test_camera.py +65 -0
  100. minigeo-0.5.7/tests/test_depth.py +93 -0
  101. minigeo-0.5.7/tests/test_exact.py +84 -0
  102. minigeo-0.5.7/tests/test_fastcast.py +209 -0
  103. minigeo-0.5.7/tests/test_frames.py +276 -0
  104. minigeo-0.5.7/tests/test_geometry_foundations.py +445 -0
  105. minigeo-0.5.7/tests/test_manual.py +97 -0
  106. minigeo-0.5.7/tests/test_measure.py +208 -0
  107. minigeo-0.5.7/tests/test_mesh.py +124 -0
  108. minigeo-0.5.7/tests/test_pose.py +195 -0
  109. minigeo-0.5.7/tests/test_scene.py +247 -0
  110. minigeo-0.5.7/tests/test_style.py +55 -0
  111. minigeo-0.5.7/tests/test_transforms.py +255 -0
  112. minigeo-0.5.7/tox.ini +7 -0
@@ -0,0 +1,50 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ # Publish on version tags, e.g. v0.7.1
7
+ - "v[0-9]+.[0-9]+.[0-9]+"
8
+ - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
9
+ - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"
10
+
11
+ jobs:
12
+ build:
13
+ runs-on: ubuntu-26.04
14
+ permissions:
15
+ contents: read
16
+ steps:
17
+ - uses: actions/checkout@v6
18
+ - name: Set up Python
19
+ uses: actions/setup-python@v6
20
+ with:
21
+ python-version: "3.12"
22
+ - name: Install uv
23
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
24
+ - name: Build
25
+ run: uv build
26
+ - name: Upload distributions as artifacts
27
+ uses: actions/upload-artifact@v6
28
+ with:
29
+ name: dist
30
+ path: dist/
31
+
32
+ publish:
33
+ needs: [build]
34
+ runs-on: ubuntu-26.04
35
+ environment:
36
+ name: pypi
37
+ permissions:
38
+ id-token: write # required for PyPI Trusted Publishing (OIDC)
39
+ steps:
40
+ - name: Install uv
41
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
42
+ with:
43
+ ignore-empty-workdir: true
44
+ - name: Download distributions artifact
45
+ uses: actions/download-artifact@v7
46
+ with:
47
+ name: dist
48
+ path: dist/
49
+ - name: Publish
50
+ run: uv publish
@@ -0,0 +1,48 @@
1
+ name: tests
2
+
3
+ on:
4
+ push:
5
+ branches: ["main"]
6
+ pull_request:
7
+ branches: ["main"]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ lint:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ - uses: astral-sh/ruff-action@v3
18
+
19
+ test:
20
+ runs-on: ubuntu-latest
21
+ strategy:
22
+ matrix:
23
+ python-version: ["3.12", "3.13", "3.14", "3.15"]
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+ with:
27
+ fetch-depth: 0 # setuptools_scm needs tags/history for the version
28
+ - uses: actions/setup-python@v5
29
+ with:
30
+ python-version: ${{ matrix.python-version }}
31
+ - name: Install
32
+ run: pip install ".[test]"
33
+ - name: Test
34
+ run: pytest --cov --cov-report=term-missing
35
+
36
+ docs:
37
+ runs-on: ubuntu-latest
38
+ steps:
39
+ - uses: actions/checkout@v4
40
+ with:
41
+ fetch-depth: 0
42
+ - uses: actions/setup-python@v5
43
+ with:
44
+ python-version: "3.12"
45
+ - name: Install
46
+ run: pip install ".[all]" -r docs/requirements.txt
47
+ - name: Build the documentation (warnings are errors)
48
+ run: sphinx-build -W --keep-going -b html docs docs/_build/html
@@ -0,0 +1,59 @@
1
+ # Temporary and binary files
2
+ *~
3
+ *.py[cod]
4
+ *.so
5
+ *.orig
6
+ *.log
7
+ *.pot
8
+ __pycache__/
9
+ .cache/*
10
+ .*.swp
11
+ .ipynb_checkpoints/
12
+ .DS_Store
13
+
14
+ # Project files
15
+ .ropeproject
16
+ .project
17
+ .pydevproject
18
+ .settings
19
+ .idea
20
+ .vscode
21
+ tags
22
+
23
+ # Package files
24
+ *.egg
25
+ *.eggs/
26
+ .installed.cfg
27
+ *.egg-info
28
+
29
+ # Unittest and coverage
30
+ htmlcov/*
31
+ .coverage
32
+ .coverage.*
33
+ .tox
34
+ junit*.xml
35
+ coverage.xml
36
+ .pytest_cache/
37
+
38
+ # Build and docs folder/files
39
+ build/*
40
+ dist/*
41
+ sdist/*
42
+ docs/api/*
43
+ docs/_rst/*
44
+ docs/_build/*
45
+ cover/*
46
+ MANIFEST
47
+
48
+ # Per-project virtualenvs
49
+ .venv*/
50
+ .conda*/
51
+ .python-version
52
+
53
+ # Tooling
54
+ .ruff_cache/
55
+ .venv/
56
+ .jupyter_ystore.db
57
+
58
+ # outputs of the example scripts
59
+ examples/*.html
@@ -0,0 +1,17 @@
1
+ # Read the Docs configuration, see https://docs.readthedocs.io/en/stable/config-file/v2.html
2
+ version: 2
3
+
4
+ build:
5
+ os: ubuntu-24.04
6
+ tools:
7
+ python: "3.12"
8
+
9
+ sphinx:
10
+ configuration: docs/conf.py
11
+
12
+ python:
13
+ install:
14
+ - requirements: docs/requirements.txt
15
+ - method: pip
16
+ path: .
17
+ extra_requirements: [all] # the backends are documented too
@@ -0,0 +1,5 @@
1
+ ============
2
+ Contributors
3
+ ============
4
+
5
+ * Alexander Steppke
@@ -0,0 +1,43 @@
1
+ =========
2
+ Changelog
3
+ =========
4
+
5
+ Version 0.0.1
6
+ ==============
7
+
8
+ - Basic geometry classes implemented
9
+
10
+ Version 0.1.0
11
+ ==============
12
+
13
+ - Added support for 3D transformations
14
+ - Separated backend-specific implementations from core geometry classes
15
+
16
+ Version 0.2.0
17
+ ==============
18
+
19
+ - API cleanup, some standardization of method names and parameters
20
+ - Animation support for geometry objects
21
+ - Improved handling of anchors for geometry placement
22
+
23
+ Version 0.4.0
24
+ ==============
25
+ - Ray tracing support for scenes
26
+
27
+ Version 0.5.0
28
+ ==============
29
+
30
+ - TikZ backend for rendering scenes as LaTeX ``tikzpicture``
31
+ - Animation support for scenes
32
+
33
+ Version 0.5.5
34
+ ==============
35
+
36
+ - Picking points on geometry objects
37
+ - Animation support for scenes
38
+
39
+ Version 0.6.0
40
+ ==============
41
+
42
+ - Numba support for faster ray tracing
43
+
@@ -0,0 +1,13 @@
1
+ ============
2
+ Contributing
3
+ ============
4
+
5
+ We welcome contributions to this project! Please follow the guidelines below to ensure a smooth collaboration process.
6
+
7
+ 1. Fork the repository and create your branch from `main`.
8
+ 2. Ensure your code follows the existing style and passes all tests.
9
+ 3. Write clear and concise commit messages.
10
+ 4. Submit a pull request describing your changes and the problem they solve.
11
+ 5. Engage in the review process and make any requested changes.
12
+
13
+ Thank you for contributing!
minigeo-0.5.7/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Alexander Steppke
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
minigeo-0.5.7/PKG-INFO ADDED
@@ -0,0 +1,345 @@
1
+ Metadata-Version: 2.4
2
+ Name: minigeo
3
+ Version: 0.5.7
4
+ Summary: A minimal interactive 3D geometry library for visualizing shapes and transformations
5
+ Author: Alexander Steppke
6
+ License-Expression: MIT
7
+ Project-URL: Source, https://github.com/asteppke/minigeo
8
+ Project-URL: Issues, https://github.com/asteppke/minigeo/issues
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Framework :: Jupyter
12
+ Classifier: Topic :: Scientific/Engineering :: Visualization
13
+ Requires-Python: >=3.12
14
+ Description-Content-Type: text/x-rst
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy>=1.23
17
+ Provides-Extra: mpl
18
+ Requires-Dist: matplotlib>=3.6; extra == "mpl"
19
+ Provides-Extra: svg
20
+ Requires-Dist: svg.py>=1.4; extra == "svg"
21
+ Provides-Extra: plotly
22
+ Requires-Dist: plotly>=5; extra == "plotly"
23
+ Requires-Dist: nbformat>=4.2; extra == "plotly"
24
+ Provides-Extra: ray
25
+ Requires-Dist: pillow>=10.1; extra == "ray"
26
+ Provides-Extra: fast
27
+ Requires-Dist: numba>=0.60; extra == "fast"
28
+ Provides-Extra: all
29
+ Requires-Dist: minigeo[mpl,plotly,ray,svg]; extra == "all"
30
+ Provides-Extra: test
31
+ Requires-Dist: pytest; extra == "test"
32
+ Requires-Dist: pytest-cov; extra == "test"
33
+ Requires-Dist: minigeo[all]; extra == "test"
34
+ Requires-Dist: numba>=0.60; python_version < "3.15" and extra == "test"
35
+ Provides-Extra: dev
36
+ Requires-Dist: minigeo[test]; extra == "dev"
37
+ Requires-Dist: ruff; extra == "dev"
38
+ Dynamic: license-file
39
+
40
+ .. image:: https://github.com/asteppke/minigeo/actions/workflows/python-app.yml/badge.svg
41
+ :alt: pytest
42
+ :target: https://github.com/asteppke/minigeo/actions/workflows/python-app.yml
43
+ .. image:: https://app.readthedocs.org/projects/minigeo/badge/?version=latest
44
+ :target: https://minigeo.readthedocs.io/en/latest/
45
+ :alt: Documentation Status
46
+ .. image:: https://mybinder.org/badge_logo.svg
47
+ :alt: Try it on Binder
48
+ :target: https://mybinder.org/v2/gh/asteppke/minigeo/HEAD?labpath=examples%2Fgetting_started.ipynb
49
+ .. image:: https://colab.research.google.com/assets/colab-badge.svg
50
+ :alt: Open in Colab
51
+ :target: https://colab.research.google.com/github/asteppke/minigeo/blob/main/examples/getting_started.ipynb
52
+
53
+
54
+ =======
55
+ minigeo
56
+ =======
57
+
58
+ A small Python library for describing and drawing basic 3D geometry, in the spirit of TikZ:
59
+ place boxes, cylinders, lines and axes relative to each other with named anchors, then draw
60
+ the scene as an SVG vector image, with matplotlib, or interactively in the browser with plotly.
61
+ It is meant for sketches and for understanding 3D geometry, readable first, fast second.
62
+
63
+ The `manual <https://minigeo.readthedocs.io/en/latest/manual/index.html>`__ introduces the
64
+ ideas one at a time, with every picture next to the code that draws it.
65
+
66
+ .. image:: https://raw.githubusercontent.com/asteppke/minigeo/main/examples/diagram.png
67
+ :alt: A sphere, a cylinder and a cone on a plate, ray traced in the "diagram" look
68
+ :width: 500px
69
+
70
+ Features
71
+ --------
72
+ - **Geometry**: ``Point``, ``Line``, ``Axis``, ``Polygon``, ``Rectangle``, ``Circle``, ``Box``,
73
+ ``Cylinder``, ``Cone`` and ``Sphere``, with named sizes: ``Cylinder(position, radius=0.5, height=2)``.
74
+ - **Measuring**: ``Vector`` (with dot and cross products), ``Plane`` (distances, projections,
75
+ intersections), ``Angle`` arcs and ``Dimension`` lines, as in technical drawings.
76
+ - **Transforms**: translation, rotation (about any axis and any point), scaling and shear as
77
+ composable 4x4 matrices: ``t @ shape``, ``t1 @ t2``.
78
+ - **Own axes**: every shape has a pose with its own perpendicular axes x', y', z' that turn
79
+ with it; ``shape.rotate("x'", 30, about="center")``.
80
+ - **Anchors**: named points such as ``"top"``, ``"bottom front left"`` or ``"near end"``, and
81
+ ``place(anchor, at=point)`` to put things next to each other.
82
+ - **Frames and joints**: chains of parts that carry each other, such as an XYZ stage or a
83
+ diffractometer, moved by sliding and turning joints: ``x.value = 0.3``.
84
+ - **Scenes and styles**: geometry is independent of drawing; a ``Scene`` adds colors, opacity,
85
+ dashes, arrows and labels.
86
+ - **Backends**: SVG (vector drawings), TikZ (for LaTeX), matplotlib (3D axes), plotly
87
+ (interactive, WebGL) and a ray tracer (light, shadows, exact spheres and cylinders, and
88
+ looks for diagrams: cel shading, outlines, ambient occlusion), all with the same camera;
89
+ scenes show themselves in Jupyter.
90
+
91
+ A first scene
92
+ -------------
93
+ .. code-block:: python
94
+
95
+ from minigeo import Box, Cylinder, Line, Scene, Style
96
+
97
+ wood = Style(fill="peru", stroke="saddlebrown")
98
+
99
+ scene = Scene()
100
+ table = scene.add(Box([0, 0, 1], size=[2, 1, 0.1], anchor="bottom"), wood)
101
+
102
+ # anchors are named points: the cup stands near the front left corner of the tabletop
103
+ cup = scene.add(Cylinder(table.anchor("top front left") + [0.3, 0.3, 0], radius=0.08, height=0.2),
104
+ fill="C0", label="cup", label_at="top")
105
+
106
+ # place() moves a shape so that one of its anchors sits on a point
107
+ book = scene.add(Box([0, 0, 0], size=[0.5, 0.35, 0.06]), fill="C3")
108
+ book.rotate("z'", 20, about="center")
109
+ book.place("bottom", at=table.anchor("top"))
110
+
111
+ scene.add(Line(cup.anchor("top"), book.anchor("top")), stroke="gray", dash="dashed")
112
+
113
+ scene # in Jupyter: shows itself as SVG
114
+ scene.save("table.svg") # or .png, .pdf (matplotlib), .html (plotly)
115
+ scene.render("matplotlib") # 3D axes
116
+ scene.render("plotly").show() # interactive in the browser
117
+ scene.save("table.png", backend="raytrace") # with light and shadows
118
+ scene.save("table.tex", width=8) # TikZ for LaTeX, 8 cm wide
119
+
120
+ All backends take the same view options: ``elev``, ``azim`` and ``vertical_axis``
121
+ (e.g. ``vertical_axis="x"`` when x points up).
122
+
123
+ Geometry and transforms
124
+ -----------------------
125
+ .. code-block:: python
126
+
127
+ from minigeo import Box, Transform
128
+
129
+ box = Box([0, 0, 0], size=(1, 2, 3)) # width, length, height (or size=1 for a cube)
130
+ Transform().translate([1, 0, 0]) @ box # transforms change the shape and return it
131
+ box.rotate("z", 45, about="center") # rotate in place around its own center
132
+ box.rotate("x'", 30, about="center") # ... or around its own x' axis
133
+
134
+ turn_then_move = Transform().translate([0, 0, 1]) @ Transform().rotate("z", 90)
135
+
136
+ copy = box.copy() # an independent copy
137
+
138
+ Round shapes take ``segments=`` (default 16), e.g. ``Sphere(position, radius=1, segments=32)``.
139
+ The old names (``BaseBox(position, dimensions=...)``, ``GeometryGroup``, ...) still work but give a
140
+ deprecation warning that names the replacement.
141
+
142
+ Anchor words refer to a shape's own axes: left/right (x'), front/back (y'), bottom/top (z').
143
+ After rotating a shape, ``shape.anchor("top")`` is still the middle of its own top face.
144
+ Lines use TikZ's positions (``"start"``, ``"near start"``, ``"midway"``, ``"near end"``,
145
+ ``"end"``, or a number), and groups (``Group``) have anchors on their bounding box.
146
+
147
+ Vectors, planes, angles and dimensions
148
+ --------------------------------------
149
+ .. code-block:: python
150
+
151
+ from minigeo import Angle, Dimension, Plane, Vector
152
+
153
+ a, b = Vector([2, 0, 0]), Vector([1, 1, 0])
154
+ a.dot(b), a.angle_to(b) # 2.0, 45.0
155
+ n = a.cross(b) # a Vector, starting where a starts
156
+
157
+ ground = Plane([0, 0, 0], normal=[0, 0, 1])
158
+ ground.distance_to([1, 2, 3]), ground.project([1, 2, 3])
159
+ ground.intersect(Vector([0, 0, -1], origin=[1, 1, 2]))
160
+
161
+ scene.add(a, label="a") # vectors are arrows; labels go to the tip
162
+ scene.add(Angle.between(a, b), label="θ") # an arc; a right angle gets a square
163
+ scene.add(Dimension(box.anchor("bottom front left"), box.anchor("bottom front right"),
164
+ offset=[0, -0.3, 0], unit=" m"))
165
+
166
+ Angles and dimension lines are drawn on top of solids, like labels, so that they stay readable.
167
+
168
+ Styles
169
+ ------
170
+ ``Style(fill=..., stroke=..., opacity=..., line_width=..., dash=..., arrow=..., text_color=...)``
171
+ holds only what is set and combines with ``|``: ``wood | Style(opacity=0.5)``. Pass a style or
172
+ single fields to ``scene.add``; single faces can be styled with ``face_styles={"top": Style(fill="gold")}``,
173
+ and ``scene.label(shape, "text", at="top")`` adds further labels that follow the shape.
174
+
175
+ For orientation, ``scene.add(shape, frame=True)`` draws the shape's own axes x', y', z' as
176
+ arrows that turn with it, and ``scene.add_frame()`` draws the world axes x, y, z at the
177
+ origin (or ``scene.add_frame(point)`` anywhere else).
178
+
179
+ Frames and joints
180
+ -----------------
181
+ A ``Frame`` is a coordinate system that carries other frames and geometry. A joint is a frame
182
+ whose position on its parent is set by one number: ``prismatic`` joints slide, ``revolute``
183
+ joints turn (in degrees). Build the parts as usual and attach them to the joint that carries
184
+ them:
185
+
186
+ .. code-block:: python
187
+
188
+ from minigeo import Box, Frame, Transform
189
+
190
+ base = Frame()
191
+ x = base.prismatic("x", limits=(0, 0.5)) # X carries Y,
192
+ y = x.prismatic("y") # Y carries Z
193
+ z = y.prismatic("z")
194
+
195
+ carriage = x.attach(Box([0, 0, 0], size=(0.3, 1, 0.05)))
196
+ head = z.attach(Box(carriage.anchor("top"), size=(0.1, 0.1, 0.1), anchor="bottom"))
197
+
198
+ x.value = 0.3 # absolute: the carriage and the head move to x = 0.3
199
+ x.move(0.05) # relative, along the joint's axis
200
+ Transform().translate([0, 0.1, 0]).in_frame(x) @ head # along x's own axes
201
+
202
+ Positions and transforms are given in world coordinates as things stand now, so anchors,
203
+ ``place`` and ``Transform() @ part`` work as before; attached parts are kept relative to their
204
+ frame and move along with it afterwards.
205
+
206
+ Animations
207
+ ----------
208
+ ``scene.animate(update, frames)`` draws the scene, then calls ``update(i)`` before each further
209
+ frame, for example to turn a box a little:
210
+
211
+ .. code-block:: python
212
+
213
+ scene.animate(lambda i: box.rotate("x'", 10, about="center"), frames=36) # plotly
214
+ scene.animate(lambda i: box.rotate("x'", 10, about="center"), frames=36,
215
+ backend="matplotlib") # matplotlib
216
+
217
+ With plotly you get a play button and a slider, and the animation also runs in an exported
218
+ HTML file. With matplotlib it plays live under ipympl (``%matplotlib widget``) and otherwise
219
+ shows as an HTML player in Jupyter; ``.save("turn.gif")`` writes a GIF. The ray tracer makes
220
+ an animated PNG, in any look, which plays wherever images are shown:
221
+
222
+ .. code-block:: python
223
+
224
+ movie = scene.animate(lambda i: box.rotate("z", 20, about="center"), frames=18,
225
+ backend="raytrace", look="diagram")
226
+ movie.save("turning.png") # or .gif, .webp
227
+
228
+ Ray tracing
229
+ -----------
230
+ ``scene.render("raytrace")`` traces rays through every pixel: faces are lit by a light from the
231
+ upper left, cast shadows on each other, and transparent faces show what lies behind them.
232
+ Spheres and cylinders are hit exactly, so they are perfectly round; intersecting solids and
233
+ lines that pass through them are drawn correctly, which the SVG and matplotlib backends
234
+ (painting faces from back to front) cannot always do. Edges, lines and labels are hidden where
235
+ something lies in front of them.
236
+
237
+ .. code-block:: python
238
+
239
+ image = scene.render("raytrace", width=1000, samples=3) # 3 x 3 rays per pixel
240
+ image.save("scene.png") # or .jpg, .webp
241
+ scene.render("raytrace", shadows=False, background="white")
242
+
243
+ It is written in numpy and takes about a second for a 500-pixel image. With the optional
244
+ ``fast`` extra (``pip install ".[ray,fast]"``), rays are cast by compiled code from numba on all
245
+ processor cores instead: several times faster, with the same pictures. It is used whenever
246
+ numba is installed; ``engine="numpy"`` or ``engine="numba"`` chooses explicitly.
247
+
248
+ For diagrams, *looks* replace the photo-like light: ``look="cel"`` (flat bands of color and
249
+ outlines), ``look="soft"`` (ambient occlusion instead of shadows), ``look="diagram"`` (both)
250
+ and ``look="print"`` (gray tones). Single settings change on top of a look:
251
+
252
+ .. code-block:: python
253
+
254
+ scene.render("raytrace", look="diagram", bands=2, outline_width=2)
255
+ scene.render("raytrace", look="cel", palette=["whitesmoke", "slategray", "goldenrod"])
256
+
257
+ TikZ
258
+ ----
259
+ ``scene.render("tikz")`` writes the scene as a ``tikzpicture`` with plain 2D coordinates,
260
+ drawn like the SVG picture. Labels are LaTeX (``"$2\theta$"``).
261
+
262
+ .. code-block:: python
263
+
264
+ picture = scene.render("tikz", width=8) # centimetres
265
+ picture.save("figure.tex") # \input{figure.tex}; needs \usetikzlibrary{arrows.meta}
266
+ picture.save("figure.pdf") # compiled with pdflatex
267
+
268
+ Installation
269
+ ------------
270
+ You can install the core minigeo library from PyPI using:
271
+
272
+ .. code-block:: bash
273
+
274
+ pip install minigeo
275
+
276
+ which only installs the library itself and the required numpy dependency.
277
+
278
+ For the full installation with all optional extras, use:
279
+
280
+ .. code-block:: bash
281
+
282
+ pip install "minigeo[all]"
283
+
284
+ which installs the matplotlib, svg, plotly and ray tracing backends, as well as the optional fast ray tracer with numba.
285
+ Individual parts can be selected by specifying the desired extras instead of ``all``.
286
+
287
+ .. code-block:: bash
288
+
289
+ pip install "minigeo[mpl,svg,plotly,ray,fast]"
290
+
291
+
292
+ The development version can be installed from this repository. Clone it and install with the desired the backends you want (``mpl``, ``svg``, ``plotly``,
293
+ ``ray``), or all of them, and optionally ``fast`` for a faster ray tracer (numba):
294
+
295
+ .. code-block:: bash
296
+
297
+ pip install -e ".[mpl,svg,plotly,ray,fast]"
298
+
299
+ For development (tests, linting and the documentation):
300
+
301
+ .. code-block:: bash
302
+
303
+ pip install -e ".[dev]" -r docs/requirements.txt
304
+ pytest
305
+ ruff check .
306
+ sphinx-build -b html docs docs/_build/html # the API reference, from the docstrings
307
+
308
+ Examples
309
+ --------
310
+ Try the examples in your browser, without installing anything: Binder starts a JupyterLab
311
+ with everything installed (it takes a minute), Colab installs minigeo in the first cell.
312
+
313
+ .. list-table::
314
+ :header-rows: 1
315
+ :widths: 30 50 10 10
316
+
317
+ * - Notebook
318
+ - Shows
319
+ - Binder
320
+ - Colab
321
+ * - ``examples/getting_started.ipynb``
322
+ - geometry, transforms, anchors, scenes, the three backends, measuring
323
+ - `launch <https://mybinder.org/v2/gh/asteppke/minigeo/HEAD?labpath=examples%2Fgetting_started.ipynb>`__
324
+ - `open <https://colab.research.google.com/github/asteppke/minigeo/blob/main/examples/getting_started.ipynb>`__
325
+ * - ``examples/animations.ipynb``
326
+ - a box turning around its own axis, with plotly and matplotlib
327
+ - `launch <https://mybinder.org/v2/gh/asteppke/minigeo/HEAD?labpath=examples%2Fanimations.ipynb>`__
328
+ - `open <https://colab.research.google.com/github/asteppke/minigeo/blob/main/examples/animations.ipynb>`__
329
+ * - ``examples/joints.ipynb``
330
+ - frames and joints: a hinge, a serial XYZ stage and a θ–2θ scan, animated
331
+ - `launch <https://mybinder.org/v2/gh/asteppke/minigeo/HEAD?labpath=examples%2Fjoints.ipynb>`__
332
+ - `open <https://colab.research.google.com/github/asteppke/minigeo/blob/main/examples/joints.ipynb>`__
333
+ * - ``examples/Cristallina.ipynb``
334
+ - a sketch of an X-ray scattering experiment, with x pointing up
335
+ - `launch <https://mybinder.org/v2/gh/asteppke/minigeo/HEAD?labpath=examples%2FCristallina.ipynb>`__
336
+ - `open <https://colab.research.google.com/github/asteppke/minigeo/blob/main/examples/Cristallina.ipynb>`__
337
+
338
+ ``examples/readme_image.py`` draws the pictures of this page; ``examples/table_scene.py`` builds a
339
+ room scene entirely with anchors;
340
+ ``examples/xyz_stage.py`` builds and animates the XYZ stage.
341
+
342
+ Contributing
343
+ ------------
344
+ Contributions are welcome! Please feel free to submit a pull request or open an issue for any
345
+ enhancements or bug fixes.