{"id":48961368,"url":"https://github.com/aidenkielby/aiden3drenderer","last_synced_at":"2026-04-23T23:00:41.486Z","repository":{"id":339066809,"uuid":"1160338457","full_name":"AidenKielby/Aiden3DRenderer","owner":"AidenKielby","description":"A real-time 3D function visualizer with a plug-and-play GPU pipeline—write simple compute shaders to create custom effects without dealing with complex rendering internals.","archived":false,"fork":false,"pushed_at":"2026-04-20T23:06:17.000Z","size":13311,"stargazers_count":12,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-21T00:40:09.085Z","etag":null,"topics":["3d-graphics","3d-mesh","3d-mesh-generation","3d-rendering","3d-to-2d","animation","compute-shaders","computer-graphics","exploration","obj","physics","physics-3d","physics-simulation","pipy-package","pygame","pygame-application","stable","wavefront-obj","xml","xml-parser"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/aiden3drenderer/1.11.6/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AidenKielby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T20:29:02.000Z","updated_at":"2026-04-20T23:05:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"a5a58e45-7a68-4980-a619-388d953a943c","html_url":"https://github.com/AidenKielby/Aiden3DRenderer","commit_stats":null,"previous_names":["aidenkielby/3d-mesh-renderer","aidenkielby/aiden3drenderer"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/AidenKielby/Aiden3DRenderer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AidenKielby%2FAiden3DRenderer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AidenKielby%2FAiden3DRenderer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AidenKielby%2FAiden3DRenderer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AidenKielby%2FAiden3DRenderer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AidenKielby","download_url":"https://codeload.github.com/AidenKielby/Aiden3DRenderer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AidenKielby%2FAiden3DRenderer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32201871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T20:19:26.138Z","status":"ssl_error","status_checked_at":"2026-04-23T20:19:23.520Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-graphics","3d-mesh","3d-mesh-generation","3d-rendering","3d-to-2d","animation","compute-shaders","computer-graphics","exploration","obj","physics","physics-3d","physics-simulation","pipy-package","pygame","pygame-application","stable","wavefront-obj","xml","xml-parser"],"created_at":"2026-04-18T02:07:12.000Z","updated_at":"2026-04-23T23:00:41.429Z","avatar_url":"https://github.com/AidenKielby.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\r\n\r\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/aiden3drenderer?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=GRAY\u0026right_color=GREEN\u0026left_text=downloads)](https://pepy.tech/projects/aiden3drenderer)\r\n[![PyPI version](https://img.shields.io/pypi/v/aiden3drenderer?color=green)](https://pypi.org/project/aiden3drenderer/)\r\n[![Python Versions](https://img.shields.io/pypi/pyversions/aiden3drenderer)](https://pypi.org/project/aiden3drenderer/)\r\n[![License: MIT](https://img.shields.io/pypi/l/aiden3drenderer)](https://github.com/AidenKielby/3D-mesh-Renderer/blob/main/LICENSE)\r\n[![PyPI status](https://img.shields.io/pypi/status/aiden3drenderer)](https://pypi.org/project/aiden3drenderer/)\r\n[![GitHub stars](https://img.shields.io/github/stars/AidenKielby/3D-mesh-Renderer?style=social)](https://github.com/AidenKielby/3D-mesh-Renderer/stargazers)\r\n[![Last commit](https://img.shields.io/github/last-commit/AidenKielby/3D-mesh-Renderer)](https://github.com/AidenKielby/3D-mesh-Renderer/commits/main)\r\n\r\n\u003c/div\u003e\r\n\r\n# Aiden3DRenderer\r\n\r\nInteractive 3D playground for learning math, Python, and GPU shaders from first principles.\r\n\r\nNo graphics background required. If you can write basic Python, you can build and understand 3D scenes here.\r\n\r\n\u003e If this project teaches you something useful, please give it a star. It helps a ton and keeps this passion project growing.\r\n\r\n## A quick note\r\n\r\nI built this because I wanted 3D graphics to feel less \"mystical\" and more hands-on.\r\nSo instead of hiding the pipeline behind a giant engine, this project keeps the core ideas visible: projection math, shape generation, shader logic, and simulation.\r\n\r\nIf you are learning, tinkering, or teaching with this repo, that is exactly what it was made for.\r\n\r\n## Who is this for?\r\n\r\n- **Math/CS students** who want to visualize 3D functions by writing one Python function.\r\n- **Python learners** who want a visual project with instant feedback instead of only terminal output.\r\n- **Aspiring graphics developers** who want to write a first GLSL (OpenGL Shader Lanuage) shader with a plug-and-play setup.\r\n\r\n## Gallery\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n  \u003ctable\u003e\r\n    \u003ctr\u003e\r\n      \u003ctd align=\"center\"\u003e\r\n        \u003cimg src=\"media/RenderShowcase.gif\" alt=\"Ripple Animation\" width=\"400\"/\u003e\r\n        \u003cbr/\u003e\r\n        \u003cb\u003eRipple Surface\u003c/b\u003e\r\n      \u003c/td\u003e\r\n      \u003ctd align=\"center\"\u003e\r\n        \u003cimg src=\"media/Spiral.gif\" alt=\"Turning Spiral\" width=\"400\"/\u003e\r\n        \u003cbr/\u003e\r\n        \u003cb\u003eAnimated Spiral\u003c/b\u003e\r\n      \u003c/td\u003e\r\n    \u003c/tr\u003e\r\n    \u003ctr\u003e\r\n      \u003ctd align=\"center\"\u003e\r\n        \u003cimg src=\"media/PhysicsDemo.gif\" alt=\"Physics Demo\" width=\"400\"/\u003e\r\n        \u003cbr/\u003e\r\n        \u003cb\u003ePhysics Playground\u003c/b\u003e\r\n      \u003c/td\u003e\r\n      \u003ctd align=\"center\"\u003e\r\n        \u003cimg src=\"media/skull_with_skybox.png\" alt=\"Rasterized Skull\" width=\"400\"/\u003e\r\n        \u003cbr/\u003e\r\n        \u003cb\u003eRasterized Skull\u003c/b\u003e\r\n      \u003c/td\u003e\r\n    \u003c/tr\u003e\r\n  \u003c/table\u003e\r\n\u003c/div\u003e\r\n\r\n## Why people love this project\r\n\r\n- Built from scratch in Python for education: the projection pipeline is implemented manually so you can read it and understand it.\r\n- You can visualize almost any mathematical surface by writing one function with `@register_shape`.\r\n- You can write GLSL compute/post shaders without heavy engine boilerplate.\r\n- Includes camera controls, OBJ loading, texture mapping, and a compact physics system for experimentation.\r\n\r\n## Start in 60 seconds\r\n\r\n```bash\r\npip install aiden3drenderer\r\n```\r\n\r\n```python\r\nfrom aiden3drenderer import Renderer3D, renderer_type\r\n\r\nrenderer = Renderer3D()\r\nrenderer.render_type = renderer_type.POLYGON_FILL\r\nrenderer.run()\r\n```\r\n\r\n## Visualize any math function\r\n\r\nYou define a shape by returning a rectangular matrix of `(x, y, z)` tuples. Decorate the function with `@register_shape`, run, and your shape appears in the scene.\r\n\r\n### Example 1: Animated ripple\r\n\r\n```python\r\nimport math\r\nfrom aiden3drenderer import register_shape\r\n\r\n@register_shape(\"Ripple\", is_animated=True, color=(150, 180, 255))\r\ndef ripple(grid_size=48, frame=0):\r\n    matrix = []\r\n    half = grid_size / 2\r\n    for i in range(grid_size):\r\n        row = []\r\n        for j in range(grid_size):\r\n            x = (i - half) / (grid_size / 8)\r\n            y = (j - half) / (grid_size / 8)\r\n            r = math.hypot(x, y) + 1e-6\r\n            z = math.sin(3.0 * r - frame * 0.12) / (1.0 + r)\r\n            row.append((x, z, y))\r\n        matrix.append(row)\r\n    return matrix\r\n```\r\n\r\n### Example 2: Gaussian hill\r\n\r\n```python\r\nimport math\r\nfrom aiden3drenderer import register_shape\r\n\r\n@register_shape(\"Gaussian Hill\", is_animated=False, color=(220, 220, 220))\r\ndef gaussian_hill(grid_size=48, frame=0):\r\n    matrix = []\r\n    half = grid_size / 2\r\n    for i in range(grid_size):\r\n        row = []\r\n        for j in range(grid_size):\r\n            x = (i - half) / (grid_size / 6)\r\n            y = (j - half) / (grid_size / 6)\r\n            z = math.exp(-(x * x + y * y))\r\n            row.append((x, z, y))\r\n        matrix.append(row)\r\n    return matrix\r\n```\r\n\r\n### Example 3: Parametric torus\r\n\r\n```python\r\nimport math\r\nfrom aiden3drenderer import register_shape\r\n\r\n@register_shape(\"Torus\", is_animated=False, color=(230, 180, 150))\r\ndef torus(grid_size=48, frame=0, R=1.5, r=0.45):\r\n    matrix = []\r\n    for i in range(grid_size):\r\n        theta = (i / grid_size) * 2 * math.pi\r\n        row = []\r\n        for j in range(grid_size):\r\n            phi = (j / grid_size) * 2 * math.pi\r\n            x = (R + r * math.cos(phi)) * math.cos(theta)\r\n            y = r * math.sin(phi)\r\n            z = (R + r * math.cos(phi)) * math.sin(theta)\r\n            row.append((x, y, z))\r\n        matrix.append(row)\r\n    return matrix\r\n```\r\n\r\n## Your first shader in 5 minutes\r\n\r\nThis is a headline feature: write a small GLSL compute shader, plug it into `CustomShader`, and run it.\r\n\r\n### Step 1: Write GLSL\r\n\r\n```glsl\r\n#version 430\r\nlayout(local_size_x = 8, local_size_y = 8) in;\r\n\r\nlayout(std430, binding = 0) buffer pixels {\r\n    vec4 data[];\r\n};\r\n\r\nuniform uint width;\r\nuniform float time;\r\n\r\nvoid main() {\r\n    uint x = gl_GlobalInvocationID.x;\r\n    uint y = gl_GlobalInvocationID.y;\r\n    uint idx = y * width + x;\r\n    float u = float(x) / float(width);\r\n    data[idx] = vec4(u, 0.5 + 0.5 * sin(time + u * 10.0), 0.25, 1.0);\r\n}\r\n```\r\n\r\n### Step 2: Dispatch from Python\r\n\r\n```python\r\nfrom aiden3drenderer import CustomShader\r\n\r\nshader_src = \"\"\"#version 430\r\nlayout(local_size_x = 8, local_size_y = 8) in;\r\nlayout(std430, binding = 0) buffer pixels { vec4 data[]; };\r\nuniform uint width;\r\nuniform float time;\r\nvoid main(){\r\n  uint x = gl_GlobalInvocationID.x;\r\n  uint y = gl_GlobalInvocationID.y;\r\n  uint idx = y * width + x;\r\n  float u = float(x) / float(width);\r\n  data[idx] = vec4(u, 0.5 + 0.5*sin(time + u*10.0), 0.25, 1.0);\r\n}\r\n\"\"\"\r\n\r\ncs = CustomShader(shader_src, context=renderer.ctx)\r\ncs.set_buffer(\"pixels\", renderer.width * renderer.height, element_size=16)\r\ncs.write_to_uniform(\"width\", renderer.width)\r\ncs.write_to_uniform(\"time\", 0.0)\r\n\r\ngroups_x = (renderer.width + 7) // 8\r\ngroups_y = (renderer.height + 7) // 8\r\ncs.compute_shader.run(groups_x, groups_y, 1)\r\n\r\npixels = cs.read_from_buffer(\"pixels\", renderer.width * renderer.height, element_type=\"vec4\")\r\n```\r\n\r\nThat is enough to start building shader effects. For more, see [docs/custom_shaders.md](docs/custom_shaders.md).\r\n\r\n## Physics playground (learn simulation by seeing it)\r\n\r\nThe physics module is intentionally lightweight and educational:\r\n\r\n- sphere objects\r\n- plane colliders\r\n- gravity and custom forces\r\n- sphere-sphere and sphere-plane collisions\r\n- optional camera physics wrapper\r\n\r\nGreat for learning integration and collision response with immediate visual feedback.\r\n\r\n## Pick your path\r\n\r\n### Path A: Learn 3D math\r\n1. Start with a built-in shape.\r\n2. Write a custom `@register_shape` function.\r\n3. Animate it with `frame`.\r\n\r\n### Path B: Learn Python through visuals\r\n1. Tweak shape loops and constants.\r\n2. Add multiple objects in one scene.\r\n3. Explore render modes and pause settings.\r\n\r\n### Path C: Learn GLSL shaders\r\n1. Copy the minimal shader above.\r\n2. Change colors and gradients.\r\n3. Add your shader to a scene as a post-processing step.\r\n\r\n---\r\n\r\n## Full technical reference (moved to the bottom)\r\n\r\nEverything is still here, just organized so beginners see the exciting part first.\r\n\r\n### Render modes\r\n\r\n- `renderer_type.MESH`\r\n- `renderer_type.POLYGON_FILL`\r\n- `renderer_type.RASTERIZE`\r\n\r\nDebug views in `RASTERIZE` mode:\r\n\r\n- `toggle_depth_view(True)`\r\n- `toggle_heat_map(True)`\r\n\r\n### Controls\r\n\r\nCamera movement:\r\n\r\n- `W/A/S/D` move forward/left/backward/right\r\n- `Space` move up\r\n- `Left Shift` move down\r\n- `Left Ctrl` speed boost\r\n- mouse wheel adjusts FOV\r\n- right mouse drag look around\r\n- arrow keys fine pitch/yaw\r\n\r\nTerrain selection keys:\r\n\r\n- `1` mountain\r\n- `2` animated waves\r\n- `3` ripple\r\n- `4` canyon\r\n- `5` pyramid\r\n- `6` spiral\r\n- `7` torus\r\n- `8` sphere\r\n- `9` mobius strip\r\n- `0` megacity\r\n- `Q` alien landscape\r\n- `E` double helix\r\n- `R` mandelbulb slice\r\n- `T` klein bottle\r\n- `Y` trefoil knot\r\n\r\nOther:\r\n\r\n- `Esc` open/close pause menu in `run()` mode\r\n\r\n### API quick reference\r\n\r\nCore:\r\n\r\n- `Renderer3D`\r\n- `register_shape`\r\n- `renderer_type`\r\n- `object_type`\r\n\r\nUseful renderer methods/attributes:\r\n\r\n- `set_starting_shape(shape_name_or_none)`\r\n- `set_use_default_shapes(bool)`\r\n- `set_render_type(renderer_type.*)`\r\n- `toggle_depth_view(bool)`\r\n- `toggle_heat_map(bool)`\r\n- `set_texture_for_raster(path)`\r\n- `add_texture_for_raster(path)`\r\n- `generate_cross_type_cubemap_skybox(radius, img_path)`\r\n- `generate_cubemap_skybox(...)`\r\n- `using_obj_filetype_format`\r\n- `vertices_faces_list`\r\n- `lighting_strictness`\r\n- `entities`\r\n\r\n### Feature docs\r\n\r\n- API index: [docs/api.md](docs/api.md)\r\n- Usage guide: [docs/usage.md](docs/usage.md)\r\n- Tutorials: [docs/tutorials.md](docs/tutorials.md)\r\n- Renderer internals: [docs/renderer.md](docs/renderer.md)\r\n- Shapes and custom shape API: [docs/shapes.md](docs/shapes.md)\r\n- Custom shaders: [docs/custom_shaders.md](docs/custom_shaders.md)\r\n- Physics: [docs/physics.md](docs/physics.md)\r\n- OBJ loader: [docs/obj_loader.md](docs/obj_loader.md)\r\n- DAE loader: [docs/dae_loader.md](docs/dae_loader.md)\r\n- Entities: [docs/entities.md](docs/entities.md)\r\n- Camera: [docs/camera.md](docs/camera.md)\r\n- Video renderer: [docs/video_renderer.md](docs/video_renderer.md)\r\n\r\n### OBJ loading notes\r\n\r\n- `obj_loader.get_obj(path, texture_index=0, offset=(x, y, z))`\r\n- N-gon faces are triangulated automatically.\r\n- UV (`vt`) data is parsed for texture mapping.\r\n\r\n### macOS note\r\n\r\n`RASTERIZE` mode needs OpenGL 4.3 compute shaders, which are not available on native macOS drivers.\r\n\r\n### Development\r\n\r\nRun from source:\r\n\r\n```bash\r\ngit clone https://github.com/AidenKielby/3D-mesh-Renderer\r\ncd 3D-mesh-Renderer/Aiden3DRenderer\r\npip install -e .\r\npython examples/basic_usage.py\r\n```\r\n\r\nBuild and publish:\r\n\r\n```bash\r\npip install build twine\r\npython -m build\r\npython -m twine upload dist/*\r\n```\r\n\r\n## Credits\r\n\r\nCreated by Aiden.\r\n\r\nSome procedural terrains, and most documentation was AI-assisted; core renderer, projection pipeline, camera, and packaging work are authored manually.\r\n\r\n### Libraries Used:\r\n- pygame (Main Window)\r\n- numpy (Accelerated Math)\r\n- opencv-python (Video Renderer)\r\n- moderngl (Compute Shaders)\r\n- pillow (Texture Loading)\r\n- lxml (DAE loading)\r\n\r\n## License\r\n\r\nAPACHE 2.0\r\n\r\n---\r\n\r\nIf this README helped you decide to try the project, a star genuinely helps this indie project reach more learners.\r\n\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidenkielby%2Faiden3drenderer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faidenkielby%2Faiden3drenderer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidenkielby%2Faiden3drenderer/lists"}