{"id":20026915,"url":"https://github.com/viktor-akusoff/chernabogpy","last_synced_at":"2026-05-15T12:31:10.442Z","repository":{"id":245761622,"uuid":"776422070","full_name":"viktor-akusoff/ChernabogPy","owner":"viktor-akusoff","description":"ChernabogPy is a Python package for visualizing gravitational distortions caused by black holes using nonlinear ray tracing.","archived":false,"fork":false,"pushed_at":"2024-07-23T18:20:17.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-30T18:40:32.396Z","etag":null,"topics":["cuda","gpu","physics-simulation","python3","relativity-of-space-and-time","torch"],"latest_commit_sha":null,"homepage":"https://imperka.tech/chernabogpy","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/viktor-akusoff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2024-03-23T13:15:32.000Z","updated_at":"2024-07-30T21:47:45.000Z","dependencies_parsed_at":"2024-06-24T01:05:23.308Z","dependency_job_id":"40a33edb-a1cd-4a1c-a392-4f0ac461bf9e","html_url":"https://github.com/viktor-akusoff/ChernabogPy","commit_stats":null,"previous_names":["viktor-akusoff/chernabogpy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/viktor-akusoff/ChernabogPy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viktor-akusoff%2FChernabogPy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viktor-akusoff%2FChernabogPy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viktor-akusoff%2FChernabogPy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viktor-akusoff%2FChernabogPy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/viktor-akusoff","download_url":"https://codeload.github.com/viktor-akusoff/ChernabogPy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viktor-akusoff%2FChernabogPy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33067082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"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":["cuda","gpu","physics-simulation","python3","relativity-of-space-and-time","torch"],"created_at":"2024-11-13T09:08:32.727Z","updated_at":"2026-05-15T12:31:10.430Z","avatar_url":"https://github.com/viktor-akusoff.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## ChernabogPy: Visualization of Gravitational Lensing by Black Holes\n\n[black-hole.webm](https://github.com/viktor-akusoff/ChernabogPy/assets/124511385/76787833-fdb5-43eb-a682-10830be4ce34)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nChernabogPy is a Python program designed to visualize gravitational lensing effects caused by black holes using a nonlinear ray tracing algorithm. The program allows you to explore the effects of spacetime curvature described by the Schwarzschild and Reissner-Nordström metrics and create realistic images of black holes.\n\nThis program was created as part of a [master's thesis](https://github.com/user-attachments/files/15948451/default.pdf).\n\n### Features:\n\n* Ray tracing considering the gravitational field of black holes:\n    * Schwarzschild metric (non-rotating, uncharged black hole)\n    * Reissner-Nordström metric (non-rotating, charged black hole)\n* Adjustment of black hole parameters (mass, charge)\n* Scene parameter customization (camera, background, objects)\n* Support for various textures:\n    * Solid colors\n    * Checkerboard patterns\n    * Loading textures from image files\n* Visualization of ray trajectories in 3D\n* Saving the rendered image\n* Loading the scene from an XML file\n* **GPU/CPU rendering** — select compute device via `--device` flag\n\n### Usage:\n\nChernabogPy uses XML files to describe the scene. The program accepts the following arguments:\n\n```\npython main.py [input.xml] [output.png] [--device auto|cuda|cpu]\n```\n\n| Argument | Default | Description |\n|---|---|---|\n| `input.xml` | `scene.xml` | Path to scene XML file |\n| `output.png` | `output.png` | Path to output PNG file |\n| `--device` | `auto` | Compute device: `auto` (detect GPU), `cuda` (force GPU), `cpu` (force CPU) |\n\nUsage examples:\n\n```bash\n# Auto-detect GPU (default)\npython main.py scene.xml output.png\n\n# Force GPU rendering\npython main.py scene.xml output.png --device cuda\n\n# Force CPU rendering (no GPU required)\npython main.py scene.xml output.png --device cpu\n\n# Use bundled test scene\npython main.py scene_test.xml output.png --device cuda\n```\n\nIf arguments are not specified, the program will use the default files `scene.xml` and `output.png`.\n\n#### XML File Structure:\n\n```xml\n\u003cscene\u003e\n    \u003ccamera\u003e\n        \u003cposition x=\"-7\" y=\"0\" z=\"1.2\"/\u003e \n        \u003clook_at x=\"0\" y=\"0\" z=\"0\"/\u003e \n        \u003cresolution width=\"640\" height=\"320\"/\u003e\n        \u003cdistance_to_screen\u003e1\u003c/distance_to_screen\u003e\n        \u003cfov\u003e1.0472\u003c/fov\u003e \n    \u003c/camera\u003e\n    \u003cobjects\u003e\n        \u003cobject type=\"sphere\"\u003e\n            \u003cposition x=\"0\" y=\"0\" z=\"0\"/\u003e\n            \u003cradius\u003e0.5\u003c/radius\u003e\n            \u003ctexture type=\"color\" r=\"0\" g=\"0\" b=\"0\"/\u003e\n        \u003c/object\u003e\n        \u003cobject type=\"sphere\"\u003e\n            \u003cposition x=\"0\" y=\"0\" z=\"0\"/\u003e\n            \u003cradius\u003e9\u003c/radius\u003e\n            \u003cinverse\u003etrue\u003c/inverse\u003e \n            \u003ctexture type=\"checkers\"\u003e\n                \u003ccolor1 r=\"0\" g=\"0.2\" b=\"0.7\"/\u003e\n                \u003ccolor2 r=\"0.3\" g=\"0.9\" b=\"0\"/\u003e\n                \u003clength\u003e25\u003c/length\u003e\n            \u003c/texture\u003e\n        \u003c/object\u003e\n        \u003cobject type=\"flat_ring\"\u003e\n            \u003cposition x=\"0\" y=\"0\" z=\"0\"/\u003e\n            \u003cinner_radius\u003e0.5\u003c/inner_radius\u003e\n            \u003couter_radius\u003e5\u003c/outer_radius\u003e\n            \u003cnorm_vector x=\"0\" y=\"0\" z=\"1\"/\u003e\n            \u003ctexture type=\"image\"\u003e\n                \u003caddress\u003e./img/rings.jpg\u003c/address\u003e\n            \u003c/texture\u003e\n        \u003c/object\u003e\n    \u003c/objects\u003e\n    \u003craytracer\u003e\n        \u003ctype\u003eReissnerNordstromRayTrace\u003c/type\u003e\n        \u003ce\u003e1\u003c/e\u003e\n        \u003ccharge\u003e0.5\u003c/charge\u003e\n        \u003ceps\u003e1e-3\u003c/eps\u003e \n    \u003c/raytracer\u003e\n\u003c/scene\u003e\n```\n\nElement Description:\n\n* **`\u003cscene\u003e`:** Root element.\n    * **`\u003ccamera\u003e`:** Camera parameters.\n        * **`\u003cposition\u003e`:** Camera position (x, y, z).\n        * **`\u003clook_at\u003e`:** Point the camera is looking at (x, y, z).\n        * **`\u003cresolution\u003e`:** Image resolution (width, height).\n        * **`\u003cdistance_to_screen\u003e`:** Distance from the camera to the screen.\n        * **`\u003cfov\u003e`:** Camera's field of view (in radians).\n    * **`\u003cobjects\u003e`:** List of scene objects.\n        * **`\u003cobject\u003e`:** Object description.\n            * **`type`:** Object type (sphere, flat_ring).\n            * **`\u003cposition\u003e`:** Object position (x, y, z).\n            * **`\u003cradius\u003e`:** Sphere radius.\n            * **`\u003cinverse\u003e`:** Invert the sphere (true/false), used for the background.\n            * **`\u003cinner_radius\u003e`:** Inner radius of the ring.\n            * **`\u003couter_radius\u003e`:** Outer radius of the ring.\n            * **`\u003cnorm_vector\u003e`:** Normal vector of the ring (x, y, z).\n            * **`\u003ctexture\u003e`:** Object texture.\n                * **`type`:** Texture type (color, checkers, image).\n                * **`r`, `g`, `b`:** Color values for solid color texture (0.0 - 1.0). \n                * **`\u003ccolor1\u003e`:** First color for the checkerboard texture (r, g, b).\n                * **`\u003ccolor2\u003e`:** Second color for the checkerboard texture (r, g, b).\n                * **`\u003clength\u003e`:** Cell size for the checkerboard texture.\n                * **`\u003caddress\u003e`:** Path to the image file for the texture.\n    * **`\u003craytracer\u003e`:** Ray tracing parameters.\n        * **`\u003ctype\u003e`:**  Ray tracer type (LinearRayTrace, SchwarzschildRayTrace, ReissnerNordstromRayTrace).\n        * **`\u003ccurvature\u003e`:** Curvature for the Schwarzschild metric.\n        * **`\u003ce\u003e`:** `e` parameter for the Reissner-Nordström metric.\n        * **`\u003ccharge\u003e`:** Charge for the Reissner-Nordström metric.\n        * **`\u003ceps\u003e`:** Ray tracing precision.\n\n### Creating an Executable:\n\n1. Install PyInstaller:\n\n   ```bash\n   pip install pyinstaller\n   ```\n\n2. Build the executable:\n\n   ```bash\n   pyinstaller --onefile main.py \n   ```\n\nThe executable file will be located in the `dist` folder.\n\n### Notes:\n\n* For faster rendering, using a GPU is recommended. Ensure you have PyTorch installed with CUDA support.\n* Without a GPU, rendering a 1024×768 scene may take 15–30 minutes. Use `--device cpu` explicitly to avoid errors on machines without CUDA.\n* Fine-tuning scene and ray tracing parameters might require some experimentation.\n* A ready-to-use test scene with procedural checkerboard textures is included as `scene_test.xml`.\n* The program's source code is available in the `chernabog` folder.\n\n### License:\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviktor-akusoff%2Fchernabogpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviktor-akusoff%2Fchernabogpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviktor-akusoff%2Fchernabogpy/lists"}