# Tiny 3D Engine
This package is a python 3D engine based on the Tkinter Canvas.
It uses Numpy for math handling.
*It is available on [pipy](https://pypi.org/project/tiny-3d-engine/),
documentation is on [readtthedocs](https://tiny-3d-engine.readthedocs.io/en/latest/), sources are mirrored on [gitlab.com](https://gitlab.com/cerfacs/tiny_3d_engine)*
Install this using
```bash
pip install tiny_3d_engine
```
It create simle 3D rendering for `bars`, `tri` and `quad` elements and store the scenes in Ensight's ASCII `.geo`format.
A trivial grid would look like:
## Loading a model
In this simple example, a .geo file is loaded `load_file_as_scene` into a 3D scene. This scene is given to a new engine object `Engine3D`. We apply a rotation `.rotate()` before rendering `.render()`the scene on the screen, then leave the interaction to the user `.mainloop()`.
```python
scene = load_file_as_scene("myfile.geo")
test = Engine3D(scene)
test.rotate('y', 45)
test.render()
test.mainloop()
```
## The SCENE and the ENGINE
The **SCENE** is an object storing the 3D model.
A void scene is simply `None`. You can update a scene with the method `.update()`. Each scene handle several parts identified by a name, a string looking either as `-tag-` (e.g. `"ceiling"`) or as `-family-.-tag-` (e.g. `"house.ceiling"`).
The **ENGINE** is used to project the scene on the 2D screen.
Once started, the view point can be contrlled by methods such as `.translate()` or `.rotate()`, then refreshed with `.render()`. The scen cane be update with `.update()`. If you want user interaction with the result, finish with the typical TK `.mainloop()`.
## What if I already have my vertices and polygons?
In the following example, two squares are appended to an initially void **Scene3D** object, using the method `scene.add_or_update_part`.
- The first, in blue, is made of edges (2 vertices connectivity)
- The second, in red, is made od squares (4 vertices connectivity)
This scene is passed to the **Engine3D** object, triggering a window.
```python
from tiny_3d_engine import (Scene3D, Engine3D)
scene = Scene3D()
SIZE = 2
LENGTH= 200.
points = list()
conn = list()
dx = LENGTH/
for i in range(SIZE):
for j in range(SIZE):
index = len(points)
points.append([i*dx, j*dx, 0])
points.append([(i+1)*dx, j*dx, 0])
points.append([i*dx, (j+1)*dx, 0])
points.append([(i+1)*dx, (j+1)*dx, 0])
conn.append([index, index+1])
conn.append([index+3, index+1])
scene.update("square1", points, conn, color="#0000ff")
points = list()
conn = list()
for i in range(SIZE):
for j in range(SIZE):
index = len(points)
points.append([i*dx, j*dx, LENGTH])
points.append([(i+1)*dx, j*dx, LENGTH])
points.append([i*dx, (j+1)*dx, LENGTH])
points.append([(i+1)*dx, (j+1)*dx, LENGTH])
conn.append([index, index+1, index+3, index+2])
scene.update("square2", points, conn, color="#ff0000")
test = Engine3D(scene)
test.rotate("x", 45)
test.rotate("y", 45)
test.render()
test.mainloop()
```
(It would have been easier in numpy, but I wanted to keep this readable for non-numpy programmers)
## Command line
A small command line interface is available:
```bash
Usage: tiny_3d_engine [OPTIONS] COMMAND [ARGS]...
--------------- TINY_3D_ENGINE --------------------
You are now using the Command line interface of Tiny 3D engine, a Python3
Tkinter lightweight 3D engine, created at CERFACS (https://cerfacs.fr).
This package is likely as a dependency of other packages, to
provide a light 3D feedback for small 3D scenes <100 000 polygons. This
CLI is given here for developers perusal and demonstrations. Find the
script of these small tools in the /examples folder of the package.
This is a python package currently installed in your python environement.
See the full documentation at :
https://tiny-3d-engine.readthedocs.io/en/latest/.
DISCLAIMER: Tiny 3D engine is a brute force flat renderer. As it is NOT
using your graphical card, do not excpect anything fancier than a 1980
video game.
Options:
--help Show this message and exit.
Commands:
bench Run a short benchmark on your machine.
load Load a 3D scene from FILENAME.
rabbit Run a demo with the Stanford Rabbit.
```
## Performances
Do not expect more than an early 90s videogame. During mouse interations, the frames per second is roughly 30 000 / nb. of polygons (i.e. 15 fps for 2000 polygons).
The engine is by default limited 100 000 polygons in a static view and 2 000 during mouse interactions. If the model goes beyond these limits, the engine ramdomly remove polygons at the loading time, to keep the window responsive.
## Requirements
The present library require Numpy and Tkinter.
The Tk aspects are limited to the **screen** object.
In the future I might write extensions for PyQT4 Canvas or Matplotlib... or not.
## Origins
This work stems from a mix between a Pure Tcl/Tk Engine of mine [ pure TK 3d engine](https://gitlab.com/cerfacs/opentea/blob/1.7/c3sm/create_viewer3d.tcl) and the the pyEngine3D-master of [henry Haefliger](https://github.com/hnhaefliger) [pyEngine3D](https://github.com/hnhaefliger/PyEngine3D) , because I really liked the API.
The present one allow several parts to be loaded, and uses numpy.
Scenes can be dumped or read from the Ensight .case/.geo files.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/cerfacstiny_3d_engine",
"name": "tiny-3d-engine",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "3D, python, tkinter",
"author": "Antoine Dauptain",
"author_email": "coop@cerfacs.fr",
"download_url": "https://files.pythonhosted.org/packages/d6/c1/91d75c86a3655e467179db8f7c1cf976db5b2c9e44d954aa74650bb856d2/tiny_3d_engine-0.3.3.tar.gz",
"platform": null,
"description": "# Tiny 3D Engine\n\n\n\nThis package is a python 3D engine based on the Tkinter Canvas.\nIt uses Numpy for math handling.\n\n*It is available on [pipy](https://pypi.org/project/tiny-3d-engine/), \ndocumentation is on [readtthedocs](https://tiny-3d-engine.readthedocs.io/en/latest/), sources are mirrored on [gitlab.com](https://gitlab.com/cerfacs/tiny_3d_engine)*\n\nInstall this using \n\n```bash\npip install tiny_3d_engine\n```\n\n\nIt create simle 3D rendering for `bars`, `tri` and `quad` elements and store the scenes in Ensight's ASCII `.geo`format.\nA trivial grid would look like:\n\n\n\n## Loading a model\n\nIn this simple example, a .geo file is loaded `load_file_as_scene` into a 3D scene. This scene is given to a new engine object `Engine3D`. We apply a rotation `.rotate()` before rendering `.render()`the scene on the screen, then leave the interaction to the user `.mainloop()`.\n\n```python\n\nscene = load_file_as_scene(\"myfile.geo\")\n\ntest = Engine3D(scene)\n\ntest.rotate('y', 45)\ntest.render()\ntest.mainloop()\n```\n\n## The SCENE and the ENGINE\n\nThe **SCENE** is an object storing the 3D model. \nA void scene is simply `None`. You can update a scene with the method `.update()`. Each scene handle several parts identified by a name, a string looking either as `-tag-` (e.g. `\"ceiling\"`) or as `-family-.-tag-` (e.g. `\"house.ceiling\"`).\n\n\n\nThe **ENGINE** is used to project the scene on the 2D screen. \nOnce started, the view point can be contrlled by methods such as `.translate()` or `.rotate()`, then refreshed with `.render()`. The scen cane be update with `.update()`. If you want user interaction with the result, finish with the typical TK `.mainloop()`.\n\n\n## What if I already have my vertices and polygons?\n\nIn the following example, two squares are appended to an initially void **Scene3D** object, using the method `scene.add_or_update_part`.\n\n- The first, in blue, is made of edges (2 vertices connectivity)\n- The second, in red, is made od squares (4 vertices connectivity)\n\nThis scene is passed to the **Engine3D** object, triggering a window.\n\n```python\nfrom tiny_3d_engine import (Scene3D, Engine3D)\n\nscene = Scene3D()\n\nSIZE = 2\nLENGTH= 200.\npoints = list()\nconn = list()\ndx = LENGTH/\n\nfor i in range(SIZE):\n for j in range(SIZE):\n index = len(points)\n points.append([i*dx, j*dx, 0])\n points.append([(i+1)*dx, j*dx, 0])\n points.append([i*dx, (j+1)*dx, 0])\n points.append([(i+1)*dx, (j+1)*dx, 0])\n conn.append([index, index+1])\n conn.append([index+3, index+1])\n \nscene.update(\"square1\", points, conn, color=\"#0000ff\")\n\npoints = list()\nconn = list()\nfor i in range(SIZE):\n for j in range(SIZE):\n index = len(points)\n points.append([i*dx, j*dx, LENGTH])\n points.append([(i+1)*dx, j*dx, LENGTH])\n points.append([i*dx, (j+1)*dx, LENGTH])\n points.append([(i+1)*dx, (j+1)*dx, LENGTH])\n conn.append([index, index+1, index+3, index+2])\nscene.update(\"square2\", points, conn, color=\"#ff0000\")\n\ntest = Engine3D(scene)\ntest.rotate(\"x\", 45)\ntest.rotate(\"y\", 45)\ntest.render()\ntest.mainloop()\n\n```\n\n(It would have been easier in numpy, but I wanted to keep this readable for non-numpy programmers)\n \n\n## Command line\n\nA small command line interface is available:\n\n```bash\nUsage: tiny_3d_engine [OPTIONS] COMMAND [ARGS]...\n\n --------------- TINY_3D_ENGINE --------------------\n\n You are now using the Command line interface of Tiny 3D engine, a Python3\n Tkinter lightweight 3D engine, created at CERFACS (https://cerfacs.fr).\n\n This package is likely as a dependency of other packages, to\n provide a light 3D feedback for small 3D scenes <100 000 polygons. This\n CLI is given here for developers perusal and demonstrations. Find the\n script of these small tools in the /examples folder of the package.\n\n This is a python package currently installed in your python environement.\n See the full documentation at :\n https://tiny-3d-engine.readthedocs.io/en/latest/.\n\n DISCLAIMER: Tiny 3D engine is a brute force flat renderer. As it is NOT\n using your graphical card, do not excpect anything fancier than a 1980\n video game.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n bench Run a short benchmark on your machine.\n load Load a 3D scene from FILENAME.\n rabbit Run a demo with the Stanford Rabbit.\n```\n\n## Performances\n\nDo not expect more than an early 90s videogame. During mouse interations, the frames per second is roughly 30 000 / nb. of polygons (i.e. 15 fps for 2000 polygons).\n\nThe engine is by default limited 100 000 polygons in a static view and 2 000 during mouse interactions. If the model goes beyond these limits, the engine ramdomly remove polygons at the loading time, to keep the window responsive. \n\n## Requirements\n\nThe present library require Numpy and Tkinter. \nThe Tk aspects are limited to the **screen** object.\nIn the future I might write extensions for PyQT4 Canvas or Matplotlib... or not.\n\n## Origins\n\nThis work stems from a mix between a Pure Tcl/Tk Engine of mine [ pure TK 3d engine](https://gitlab.com/cerfacs/opentea/blob/1.7/c3sm/create_viewer3d.tcl) and the the pyEngine3D-master of [henry Haefliger](https://github.com/hnhaefliger) [pyEngine3D](https://github.com/hnhaefliger/PyEngine3D) , because I really liked the API.\n\nThe present one allow several parts to be loaded, and uses numpy.\nScenes can be dumped or read from the Ensight .case/.geo files.\n",
"bugtrack_url": null,
"license": null,
"summary": "Open source tiny 3D engine for tkinter",
"version": "0.3.3",
"project_urls": {
"Bug Tracker": "https://gitlab.com/cerfacs/tiny_3d_engine/-/issues",
"Documentation": "https://tiny_3d_engine.readthedocs.io/en/latest/",
"Homepage": "https://gitlab.com/cerfacs/tiny_3d_engine"
},
"split_keywords": [
"3d",
" python",
" tkinter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "684de25f03c43b881a611f333f2e63c3cf88bbb4a6b44aaaa1a9880f68597a15",
"md5": "50be22d992af6e1364c62e3a7c65bb03",
"sha256": "94fa5144e8a34e83c8bbfb066e7d562f1d5edc3347d0fcdf773d4be919cba9af"
},
"downloads": -1,
"filename": "tiny_3d_engine-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50be22d992af6e1364c62e3a7c65bb03",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 28675,
"upload_time": "2024-12-05T15:34:12",
"upload_time_iso_8601": "2024-12-05T15:34:12.448567Z",
"url": "https://files.pythonhosted.org/packages/68/4d/e25f03c43b881a611f333f2e63c3cf88bbb4a6b44aaaa1a9880f68597a15/tiny_3d_engine-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d6c191d75c86a3655e467179db8f7c1cf976db5b2c9e44d954aa74650bb856d2",
"md5": "738ae88d47c4b212125acddc109b1bbe",
"sha256": "37b840d36da10c16134aeb17b6fc36762dca41df14db9b320acce2e7fa52f8cd"
},
"downloads": -1,
"filename": "tiny_3d_engine-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "738ae88d47c4b212125acddc109b1bbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 394794,
"upload_time": "2024-12-05T15:34:14",
"upload_time_iso_8601": "2024-12-05T15:34:14.702948Z",
"url": "https://files.pythonhosted.org/packages/d6/c1/91d75c86a3655e467179db8f7c1cf976db5b2c9e44d954aa74650bb856d2/tiny_3d_engine-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-05 15:34:14",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "cerfacs",
"gitlab_project": "tiny_3d_engine",
"lcname": "tiny-3d-engine"
}
JSON