Metadata-Version: 2.4
Name: ggb3tikz
Version: 0.1.0
Summary: Export GeoGebra 3D constructions to TikZ with explicit camera projection.
Author: Saroyr
License-Expression: MIT
Project-URL: Homepage, https://github.com/saro2808/ggb3tikz
Project-URL: Issues, https://github.com/saro2808/ggb3tikz/issues
Keywords: geogebra,tikz,latex,3d,geometry,converter
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ggb3tikz

`ggb3tikz` exports a useful subset of GeoGebra 3D `.ggb` files to TikZ by
reading `geogebra.xml`, projecting 3D coordinates with an explicit camera, and
writing ordinary 2D TikZ paths.

It currently supports:

- free 3D points with `<coords x="..." y="..." z="..." w="...">`
- segments, lines, rays, polygons, pyramids, planes, circles, ellipses, conics,
  spheres, and angles when their GeoGebra data resolves to supported geometry
- labels, captions, colors, point styles, line thickness, line patterns, fills,
  opacity, and visibility flags
- hidden objects as TikZ definitions without drawing them
- painter-style depth sorting by average camera depth

## Usage

From this repository directory:

```bash
python3 -m ggb3tikz input.ggb -o output.tex --view 6,-8,5 --target 0,0,0 --distance 14 --scale 1.2
```

From the parent directory, include the repository path:

```bash
python3 -m ggb3tikz ggb3tikz/input.ggb -o ggb3tikz/output.tex --view 6,-8,5 --target 0,0,0 --distance 14 --scale 1.2
```

Camera options:

- `--view x,y,z`: view direction, interpreted as camera position direction from
  the target.
- `--target x,y,z`: point the camera looks at.
- `--distance d`: distance from camera to target.
- `--ortho`: force orthographic projection.
- `--perspective`: use perspective projection.
- `--up x,y,z`: camera up hint.

The output is a standalone LaTeX document by default. Use `--fragment` to emit
only the `tikzpicture`.

## Example

The repository includes `313dode.ggb`, a dodecahedron 3D construction with
filled faces, a sphere, points, labels, and depth ordering.

![313dode example rendered by ggb3tikz](examples/313dode.png)

From the parent `projects` directory, generate it with:

```bash
python3 -m ggb3tikz ggb3tikz/313dode.ggb -o ggb3tikz/313dode.tex --view 0.16,-0.96,0.2 --target 0,0,0 --distance 14 --scale 2.4
```

Or, from inside this repository:

```bash
python3 -m ggb3tikz 313dode.ggb -o 313dode.tex --view 0.16,-0.96,0.2 --target 0,0,0 --distance 14 --scale 2.4
```

Compile the result with:

```bash
pdflatex 313dode.tex
```

For very depth-sensitive curves, add `--segment-curves-for-depth`. That can
improve painter ordering for crossing curves, but it intentionally produces much
larger TikZ output.

## Limitations

This project is an approximate converter, not a full replacement for GeoGebra's
own 3D renderer. It is meant to produce a good TikZ starting point for
mathematical figures, after which manual adjustment may still be needed.

Known limitations:

- There is no true z-buffer. Objects are sorted with a painter-style depth
  ordering, so partial occlusion can still be wrong when curves or faces pass in
  front of and behind each other.
- Transparent surfaces are especially difficult because correct rendering
  depends on splitting geometry at intersections and compositing fragments in
  depth order.
- Plane rendering is approximate. Planes are exported as finite patches chosen
  from the detected scene scale, not as GeoGebra's exact viewport-clipped
  infinite planes.
- Curves are usually exported as compact smooth TikZ paths. This keeps files
  readable, but it means a whole curve has one approximate depth. Use
  `--segment-curves-for-depth` when depth ordering of curves matters more than
  output size.
- Some GeoGebra objects may still be unsupported or only partly reconstructed,
  especially when their XML representation depends on hidden helper objects or
  app-specific rendering behavior.
- Labels and styles are preserved where practical, but exact font metrics,
  label placement, and every GeoGebra style detail are not guaranteed.

Future improvements could include better curve/surface intersection splitting,
more faithful plane clipping, a richer style model, more GeoGebra command
coverage, optional Asymptote or SVG backends, and a visual regression test suite
based on small `.ggb` examples.

## Packaging

The package version is stored in `pyproject.toml`:

```toml
version = "0.1.0"
```

Before publishing a new release, update that version, then build the source and
wheel distributions:

```bash
python3 -m pip install --upgrade build twine
python3 -m build
```

Check the generated package metadata:

```bash
python3 -m twine check dist/*
```

Upload to TestPyPI first:

```bash
python3 -m twine upload --repository testpypi dist/*
```

If the TestPyPI package installs and runs correctly, upload to PyPI:

```bash
python3 -m twine upload dist/*
```

The tests are intentionally smoke tests rather than proof of visual perfection:
they check that representative `.ggb` files parse and export without crashing
and that expected TikZ structures are present. The final geometry still needs
visual inspection because depth ordering, transparency, and labels are rendering
problems, not just text-output problems.

## Credit

This converter was written with OpenAI Codex in collaboration with the project
author. The implementation is intentionally kept as ordinary Python code so it
can be inspected, modified, packaged, and improved like any other open-source
tool.
