Metadata-Version: 2.4
Name: axonometry
Version: 0.2.0rc1
Summary: Scripting library for generating axonometric drawings.
Author: Julien Rippinger
License-Expression: GPL-3.0-or-later
Project-URL: Documentation, https://axonometry.readthedocs.io/
Project-URL: Codeberg, https://codeberg.org/mononym/axonometry/
Project-URL: Changelog, https://axonometry.readthedocs.io/latest/changelog.html
Project-URL: Issues, https://codeberg.org/mononym/axonometry/issues
Keywords: architecture,research,drawing,axonometry,projection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Artistic Software
Classifier: Topic :: Education
Classifier: Topic :: Multimedia :: Graphics :: Editors :: Vector-Based
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/x-rst
License-File: LICENSES/GPL-3.0-or-later.txt
Requires-Dist: compas~=2.10
Requires-Dist: vpype[all]~=1.14
Requires-Dist: shapely>=2.0
Requires-Dist: numpy
Requires-Dist: svgwrite
Requires-Dist: CairoSVG
Dynamic: license-file

.. SPDX-FileCopyrightText: 2022-2026 Julien Rippinger
..
.. SPDX-License-Identifier: CC-BY-4.0

axonometry
==========

.. start-axonometry

**axonometry draws three-dimensional objects the way they were drawn by hand: by projection.**

A Python scripting library for axonometric drawings, made for pen plotters.
A script states projection operations --- a line in the plan, its projection into space, the intersection of two lines --- and every point of the image is found where two projection lines cross, as on a drafting table.
It is part of a doctoral research project in architectural representation at the `AlICe laboratory <https://alicelab.be>`__ (Université libre de Bruxelles).

.. image:: https://codeberg.org/mononym/axonometry/raw/branch/main/docs/source/_images/figures/tutorial_hatched.png
   :alt: A hatched volume constructed from its plan and an elevation, with its construction traces.
   :align: center

📖 **Documentation:** https://axonometry.readthedocs.io — tutorial, how-to guides, the geometry behind the library, and the API reference.

Install
-------

Python 3.11 to 3.13 (3.13 recommended). The simplest way is `uv <https://docs.astral.sh/uv/>`__, which fetches Python and the library to run a script:

.. code:: sh

   uv run --python 3.13 --with axonometry script.py
   uv run --python 3.13 --prerelease=allow --with axonometry script.py   # release candidates

or install it like any package: ``pip install axonometry``.

How it works
------------

.. code:: python

   from axonometry import Axonometry, Line, Point

   my_axo = Axonometry(30, 30)                       # an isometric system
   line = my_axo.xy.draw_line(Line(Point(x=70, y=40), Point(x=70, y=15)))  # a line in the plan
   line.project(distance=80)                         # the same line, 80 mm above the plan
   my_axo.save_svg("first_drawing")                  # the SVG file, in ./output/

An axonometry is four planes: the picture plane, where points have three coordinates, and three reference planes --- the plan ``xy`` and the elevations ``yz`` and ``zx`` --- tilted into the paper.
A point in space is never computed by a projection matrix.
Its views are drawn in two reference planes, and the point is where their projection lines cross:

.. code:: text

   view in xy ─┐
               ├→ projection lines → intersection → point in the picture plane
   view in zx ─┘

The construction stays in the drawing, on its own layer: the SVG file has one layer per pen (system, construction traces, geometry, hatches), with the paths in the order of the construction.
Many defaults are random: the same script never makes quite the same drawing.

Development
-----------

.. code:: sh

   git clone https://codeberg.org/mononym/axonometry.git
   cd axonometry
   git switch dev             # contributions branch from dev
   uv sync                    # package + dev dependencies

.. list-table::
   :widths: 30 70

   * - Test
     - ``uv run python -m unittest discover tests``
   * - Lint
     - ``uv tool run ruff check && uv tool run ruff format --diff``
   * - Licenses
     - ``uvx reuse lint``
   * - Docs
     - ``uv run sphinx-autobuild docs/source docs/build``
   * - Figures
     - ``uv run python docs/source/_scripts/figures.py`` (after a change that affects the drawings)

CI (Woodpecker) runs the tests on Python 3.11, 3.12 and 3.13, the lint and the license check.

Layout:

.. code:: text

   src/axonometry/
     axonometry.py          the entry point: a system, its four planes and its drawing
     trihedron.py           the axes on the paper and the tilt of the reference planes
     plane.py               picture plane and reference planes, where geometry is drawn
     point.py, line.py      the elements; the line is the element of a plotter drawing
     surface.py, volume.py  closed polygons and prisms
     hatch.py               fill styles, measured in true size
     operations.py          geometric questions answered by construction
     drawing.py, paper.py   the record of the paths, SVG export, papers and pens
     axo_config.toml        layers, pens and colors
   docs/source/             Sphinx docs (tutorial, how-to, explanation, reference)
   examples/                example scripts and files

Before adding a feature, read the `design principles <https://axonometry.readthedocs.io/latest/explanation/principles.html>`__ and the `contribution guide <https://axonometry.readthedocs.io/latest/reference/contributing.html>`__.
Feedback of any kind is welcome, and doesn't require software development skills.

Issues and contributions: https://codeberg.org/mononym/axonometry/issues

Acknowledgements
----------------

- `compas <https://compas.dev>`__ for the geometry and `vpype <https://vpype.readthedocs.io>`__ for the plotter-ready SVG. Not only did their libraries make this project possible, but reading their codebases was an invaluable way to learn Python.

Licenses
--------

- axonometry: `GNU General Public License v3.0 or later <https://www.gnu.org/licenses/gpl-3.0-standalone.html>`__
- documentation & images: `Creative Commons Attribution 4.0 International <https://creativecommons.org/licenses/by/4.0/>`__
- test drawing ``tests/bunny.svg``: `Creative Commons Attribution-ShareAlike 4.0 International <https://creativecommons.org/licenses/by-sa/4.0/>`__
- configuration, CI and generated files: `CC0 1.0 Universal <https://creativecommons.org/publicdomain/zero/1.0>`__

.. end-axonometry
