https://github.com/viktor-akusoff/chernabogpy
ChernabogPy is a Python package for visualizing gravitational distortions caused by black holes using nonlinear ray tracing.
https://github.com/viktor-akusoff/chernabogpy
cuda gpu physics-simulation python3 relativity-of-space-and-time torch
Last synced: about 1 month ago
JSON representation
ChernabogPy is a Python package for visualizing gravitational distortions caused by black holes using nonlinear ray tracing.
- Host: GitHub
- URL: https://github.com/viktor-akusoff/chernabogpy
- Owner: viktor-akusoff
- License: mit
- Created: 2024-03-23T13:15:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-23T18:20:17.000Z (almost 2 years ago)
- Last Synced: 2025-07-30T18:40:32.396Z (11 months ago)
- Topics: cuda, gpu, physics-simulation, python3, relativity-of-space-and-time, torch
- Language: Python
- Homepage: https://imperka.tech/chernabogpy
- Size: 36.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## ChernabogPy: Visualization of Gravitational Lensing by Black Holes
[black-hole.webm](https://github.com/viktor-akusoff/ChernabogPy/assets/124511385/76787833-fdb5-43eb-a682-10830be4ce34)
[](https://opensource.org/licenses/MIT)
ChernabogPy 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.
This program was created as part of a [master's thesis](https://github.com/user-attachments/files/15948451/default.pdf).
### Features:
* Ray tracing considering the gravitational field of black holes:
* Schwarzschild metric (non-rotating, uncharged black hole)
* Reissner-Nordström metric (non-rotating, charged black hole)
* Adjustment of black hole parameters (mass, charge)
* Scene parameter customization (camera, background, objects)
* Support for various textures:
* Solid colors
* Checkerboard patterns
* Loading textures from image files
* Visualization of ray trajectories in 3D
* Saving the rendered image
* Loading the scene from an XML file
* **GPU/CPU rendering** — select compute device via `--device` flag
### Usage:
ChernabogPy uses XML files to describe the scene. The program accepts the following arguments:
```
python main.py [input.xml] [output.png] [--device auto|cuda|cpu]
```
| Argument | Default | Description |
|---|---|---|
| `input.xml` | `scene.xml` | Path to scene XML file |
| `output.png` | `output.png` | Path to output PNG file |
| `--device` | `auto` | Compute device: `auto` (detect GPU), `cuda` (force GPU), `cpu` (force CPU) |
Usage examples:
```bash
# Auto-detect GPU (default)
python main.py scene.xml output.png
# Force GPU rendering
python main.py scene.xml output.png --device cuda
# Force CPU rendering (no GPU required)
python main.py scene.xml output.png --device cpu
# Use bundled test scene
python main.py scene_test.xml output.png --device cuda
```
If arguments are not specified, the program will use the default files `scene.xml` and `output.png`.
#### XML File Structure:
```xml
1
1.0472
0.5
9
true
25
0.5
5
./img/rings.jpg
ReissnerNordstromRayTrace
1
0.5
1e-3
```
Element Description:
* **``:** Root element.
* **``:** Camera parameters.
* **``:** Camera position (x, y, z).
* **``:** Point the camera is looking at (x, y, z).
* **``:** Image resolution (width, height).
* **``:** Distance from the camera to the screen.
* **``:** Camera's field of view (in radians).
* **``:** List of scene objects.
* **``:** Object description.
* **`type`:** Object type (sphere, flat_ring).
* **``:** Object position (x, y, z).
* **``:** Sphere radius.
* **``:** Invert the sphere (true/false), used for the background.
* **``:** Inner radius of the ring.
* **``:** Outer radius of the ring.
* **``:** Normal vector of the ring (x, y, z).
* **``:** Object texture.
* **`type`:** Texture type (color, checkers, image).
* **`r`, `g`, `b`:** Color values for solid color texture (0.0 - 1.0).
* **``:** First color for the checkerboard texture (r, g, b).
* **``:** Second color for the checkerboard texture (r, g, b).
* **``:** Cell size for the checkerboard texture.
* **`
`:** Path to the image file for the texture.
* **``:** Ray tracing parameters.
* **``:** Ray tracer type (LinearRayTrace, SchwarzschildRayTrace, ReissnerNordstromRayTrace).
* **``:** Curvature for the Schwarzschild metric.
* **``:** `e` parameter for the Reissner-Nordström metric.
* **``:** Charge for the Reissner-Nordström metric.
* **``:** Ray tracing precision.
### Creating an Executable:
1. Install PyInstaller:
```bash
pip install pyinstaller
```
2. Build the executable:
```bash
pyinstaller --onefile main.py
```
The executable file will be located in the `dist` folder.
### Notes:
* For faster rendering, using a GPU is recommended. Ensure you have PyTorch installed with CUDA support.
* Without a GPU, rendering a 1024×768 scene may take 15–30 minutes. Use `--device cpu` explicitly to avoid errors on machines without CUDA.
* Fine-tuning scene and ray tracing parameters might require some experimentation.
* A ready-to-use test scene with procedural checkerboard textures is included as `scene_test.xml`.
* The program's source code is available in the `chernabog` folder.
### License:
MIT License