{"id":35174955,"url":"https://github.com/aaronsb/ray","last_synced_at":"2026-05-19T18:10:19.692Z","repository":{"id":329890139,"uuid":"1120889775","full_name":"aaronsb/ray","owner":"aaronsb","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-28T19:30:28.000Z","size":11677,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-31T10:25:22.513Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-22T05:31:28.000Z","updated_at":"2025-12-28T19:04:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aaronsb/ray","commit_stats":null,"previous_names":["aaronsb/ray"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/ray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/ray/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fray/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33227246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-19T15:49:41.270Z","status":"ssl_error","status_checked_at":"2026-05-19T15:49:22.917Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":[],"created_at":"2025-12-28T22:07:07.434Z","updated_at":"2026-05-19T18:10:19.686Z","avatar_url":"https://github.com/aaronsb.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ray's Bouncy Castle\n\nA GPU-accelerated path tracer using Vulkan compute shaders with support for CSG primitives, Bezier patches (Utah teapot), and physically-based materials. Scenes are defined using a clean S-expression format.\n\n![Path Tracer Screenshot](docs/media/screenshot.png)\n\n## Features\n\n- **GPU Path Tracing**: Real-time progressive rendering using Vulkan compute shaders\n- **CSG Primitives**: Sphere, box, cylinder, cone, torus with boolean operations (union, subtract, intersect)\n- **Bezier Patches**: Bicubic parametric surfaces with Newton-Raphson ray tracing (Utah teapot included)\n- **Physically-Based Materials**: Diffuse, metal, glass, emissive with configurable properties\n- **S-Expression Scene Format**: Clean, declarative scene definition with includes support\n- **Interactive Camera**: Orbit controls with mouse (drag to rotate, scroll to zoom)\n\n## Quick Start\n\n```bash\n# Build\nmkdir build \u0026\u0026 cd build\ncmake ..\ncmake --build .\n\n# Run with demo scene\n./ray --scene ../scenes/demo.scene\n\n# Take screenshot after 100 frames\n./ray --scene ../scenes/teapot.scene --screenshot teapot.png --frames 100\n```\n\n## Requirements\n\n- **CMake** 3.20 or higher\n- **Qt6** (Core, Gui, Widgets)\n- **Vulkan SDK** 1.2 or higher\n- **glslc** shader compiler (included with Vulkan SDK)\n- C++17 compatible compiler\n\n### Installing Dependencies\n\n**Arch Linux:**\n```bash\nsudo pacman -S cmake qt6-base vulkan-devel\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt install cmake qt6-base-dev vulkan-sdk\n```\n\n**macOS:**\n```bash\nbrew install cmake qt6 vulkan-sdk\n```\n\n## Building\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake ..\ncmake --build .\n```\n\nFor optimized release build:\n```bash\ncmake -DCMAKE_BUILD_TYPE=Release ..\ncmake --build .\n```\n\n## Usage\n\n### Command Line Options\n\n```bash\n./ray [OPTIONS]\n\nOptions:\n  -s, --scene \u003cfile\u003e       Load scene file (.scene format)\n  --screenshot \u003cfile\u003e      Take screenshot and optionally exit\n  --frames \u003ccount\u003e         Frames to accumulate before screenshot (default: 30)\n  --no-exit               Don't exit after screenshot (keep window open)\n  -d, --debug             Enable Vulkan validation layers\n  -h, --help              Show help message\n  -v, --version           Show version\n```\n\n### Examples\n\n```bash\n# Load and display a scene\n./ray --scene scenes/demo.scene\n\n# Render scene to image (headless mode)\n./ray --scene scenes/demo.scene --screenshot output.png --frames 200\n\n# Debug mode with validation layers\n./ray --scene scenes/demo.scene --debug\n\n# Interactive mode with screenshot option\n./ray --scene scenes/demo.scene --screenshot output.png --no-exit\n```\n\n### Interactive Controls\n\n- **Left mouse drag**: Orbit camera around scene\n- **Right mouse drag**: Pan camera\n- **Scroll wheel**: Zoom in/out\n- **S**: Save screenshot to `screenshot.png`\n- **Esc**: Quit application\n\n## Scene Files\n\nScenes are defined using S-expressions. Here's a minimal example:\n\n```lisp\n; Define materials\n(material red (type metal) (rgb 0.9 0.2 0.2) (roughness 0.05))\n(material glass (type glass) (rgb 0.95 0.95 0.95) (ior 1.5))\n\n; Add primitives\n(shape (sphere (at 0 1 0) (r 1.0)) red)\n(shape (box (at 3 1 0) (half 0.8 0.8 0.8)) glass)\n\n; CSG operations\n(shape (subtract\n         (sphere (at -3 1 0) (r 1.2))\n         (box (at -3 1 0) (half 0.6 1.5 0.6)))\n       red)\n\n; Bezier patch instances (Utah teapot)\n(include \"teapot.scene\")\n(instance teapot (at 0 0 -5) (scale 0.5) (rotate 0 45 0) glass)\n```\n\nSee [docs/scene-format.md](docs/scene-format.md) for complete syntax reference.\n\n## Project Structure\n\n```\nraydemo/\n├── src/\n│   ├── core/                   # Core rendering library (header-only)\n│   │   ├── types.h            # Vec3, math utilities\n│   │   ├── scene.h            # Scene container (legacy)\n│   │   ├── materials.h        # Material types\n│   │   └── renderer.h/cpp     # Vulkan renderer\n│   │\n│   ├── parametric/            # Parametric primitives library\n│   │   ├── types.h            # Shared types (Vec3, AABB, Ray)\n│   │   ├── bezier/            # Bezier patch implementation\n│   │   │   ├── patch.h        # Patch data structure\n│   │   │   ├── subdivision.h # De Casteljau subdivision\n│   │   │   ├── bvh.h          # BVH acceleration\n│   │   │   └── instance.h     # Transform instances\n│   │   ├── csg/               # CSG tree data structures\n│   │   │   └── csg.h          # CSGScene, CSGNode, CSGPrimitive\n│   │   ├── materials/         # Material library\n│   │   │   └── material.h     # MaterialLibrary\n│   │   └── scene/             # Scene loader\n│   │       ├── sexp.h         # S-expression parser\n│   │       └── scene_loader.h # .scene file loader\n│   │\n│   └── apps/                  # Applications\n│       ├── ray/               # Main ray tracer\n│       │   ├── main.cpp       # Entry point\n│       │   └── ray_renderer.cpp\n│       └── scenecheck/        # Scene file validator\n│           └── main.cpp\n│\n├── shaders/\n│   ├── ray.comp              # Main compute shader\n│   └── includes/\n│       ├── bezier.glsl       # Bezier intersection (Newton-Raphson)\n│       ├── csg.glsl          # CSG tree traversal\n│       ├── sdf.glsl          # Signed distance functions\n│       ├── materials.glsl    # Material scattering\n│       ├── geometry.glsl     # Ray-primitive intersections\n│       ├── noise.glsl        # Procedural noise\n│       └── random.glsl       # RNG (PCG)\n│\n├── scenes/                    # Example scene files\n│   ├── demo.scene            # CSG showcase + teapots\n│   └── teapot.scene          # Utah teapot Bezier patch data\n│\n└── docs/\n    ├── architecture.md       # Code structure overview\n    ├── scene-format.md       # Scene file syntax reference\n    ├── materials.md          # Material system guide\n    └── adr/                  # Architecture Decision Records\n```\n\n## Documentation\n\n- [Architecture Guide](docs/architecture.md) - Code structure and data flow\n- [Scene Format Reference](docs/scene-format.md) - Complete .scene file syntax\n- [Materials Guide](docs/materials.md) - Material types and properties\n- [ADRs](docs/adr/) - Architecture Decision Records\n\n## CLI Tools\n\n### scenecheck\n\nValidates scene files and reports statistics:\n\n```bash\n./scenecheck ../scenes/demo.scene\n```\n\nOutput:\n```\nScene loaded successfully!\nPrimitives: 45\nCSG nodes: 92\nMaterials: 6\nPatch groups: 1 (teapot: 32 patches)\nInstances: 2\n```\n\n## Technical Details\n\n- **Compute shader based**: No hardware ray tracing required (runs on any Vulkan 1.2 GPU)\n- **Newton-Raphson intersection**: Direct ray-Bezier intersection without tessellation\n- **De Casteljau subdivision**: CPU-side patch subdivision for BVH acceleration\n- **SDF-based CSG**: Smooth boolean operations using signed distance fields\n- **Progressive accumulation**: Multi-sample anti-aliasing with temporal accumulation\n\n## Performance\n\nTypical performance on RTX 3070 (1920x1080):\n- Simple scenes (5-10 primitives): 60 fps\n- Complex CSG (40+ operations): 30-45 fps\n- Bezier patches (Utah teapot): 60+ fps with BVH\n\n## Contributing\n\nThis is a personal research project. Issues and pull requests welcome.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## References\n\n- [ADR-007: SDF-based CSG](docs/adr/ADR-007-sdf-based-csg.md)\n- [ADR-008: Parametric Primitives Library](docs/adr/ADR-008-parametric-primitives-library.md)\n- Kajiya 1982: Ray Tracing Parametric Patches\n- Inigo Quilez: SDF functions and CSG operations\n\n## Acknowledgments\n\n- **Utah Teapot**: Original model by Martin Newell (1975)\n- **S-Expression Parser**: Custom implementation for scene format\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fray/lists"}