caustics 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07a93d859b9558e27661a91aab00238fa15788a739c3c9abba0c45694e65551c
-  data.tar.gz: 90105dc64c843e76cbe7cfd6a7cfe73d56313aad8652f93e04fc881cd542f1bc
+  metadata.gz: 10c88b54baa715ecbb00dc89d92a450a11376482b271b62830ecb3bdcaf07e8b
+  data.tar.gz: f1784ca8a4e044c45d632f467dc30109e57b6ee9b2f02b635c45062941cf661a
 SHA512:
-  metadata.gz: 4502f7ff407720bf3d647607a0b5d6984ef7efebbd44a13840c6b29869e1b20dd0cb2b9d5307f5f63bea2dac493024bb898021a48999578477e81c14d10b2a15
-  data.tar.gz: c012eb9814e5089bb52dd94e102960d170baa4a771072f4912adc69e4f5ef6e3a4d5aedef3ab6ce54381212d9759d4ca4c7379e9eb935ccb6ab08a019400804d
+  metadata.gz: 8f6205eef7c6d43866cacefaf43a95163c0d8b067567f659faf622e297fc1a43a2b93993f4764973b247cc391acb66eeceda5e1199ffedf767edfbcd9c8c410f
+  data.tar.gz: 0dcea5536f7219d8a1161faeda31f86bcb2b4b8bdb61ca8a598b5ab3925b74601df16f02315caf127ef514da5a7ecc50f685544eb9cfb55ed0074d26a11b1205

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-25
+
+- Add cumulative GIF output to `caustics render` through optional Flipbook.
+
 ## [0.1.0] - 2026-09-23
 
-- Initial release.
+- Initial release.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2026 ydah
+Copyright (c) 2026 Yudai Takada
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,19 +1,19 @@
-# Caustics
+<h1 align="center">Caustics</h1>
 
-[![Gem version](https://badge.fury.io/rb/caustics.svg)](https://rubygems.org/gems/caustics)
-[![Downloads](https://img.shields.io/gem/dt/caustics?label=downloads)](https://rubygems.org/gems/caustics)
-[![CI](https://github.com/rbgfx/caustics/actions/workflows/ci.yml/badge.svg)](https://github.com/rbgfx/caustics/actions/workflows/ci.yml)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D3.1-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
-[![License](https://img.shields.io/badge/license-MIT-750014.svg)](LICENSE.txt)
+<p align="center">A deterministic pure Ruby path tracer and teaching example.</p>
 
-> A deterministic pure Ruby path tracer and teaching example.
+<p align="center">
+  <a href="https://rubygems.org/gems/caustics"><img src="https://badge.fury.io/rb/caustics.svg" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/caustics"><img src="https://img.shields.io/gem/dt/caustics?label=downloads" alt="Downloads"></a>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D3.1-CC342D?logo=ruby&amp;logoColor=white" alt="Ruby Version"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-750014.svg" alt="License"></a>
+</p>
 
-Caustics is a small ray tracer for experimenting with cameras, materials,
-textures, acceleration, and renderer backends. The Ruby engine is the reference
-implementation; optional rlsl and Metal engines cover a deliberately smaller
-shader subset.
+[Features](#features) · [Installation](#installation) · [Quick Start](#quick-start) · [Engines](#engines)
 
-**[Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Engines](#engines) · [Development](#development)**
+***
+
+Caustics is a small ray tracer for experimenting with cameras, materials, textures, acceleration, and renderer backends. The Ruby engine is the reference implementation; optional RLSL and Metal engines cover a deliberately smaller shader subset.
 
 ## Features
 
@@ -44,15 +44,23 @@ Or install the released gem:
 gem install caustics
 ~~~
 
-## Quick start
+### Requirements
+
+- Ruby 3.1 or newer.
+- The Metal engine requires macOS with a Metal-capable device.
+
+## Quick Start
 
 Render the included scene:
 
 ~~~sh
 caustics render scenes/weekend.rb --size 400x225 --spp 16 --workers 4 -o out.png
+caustics render scenes/weekend.rb --size 400x225 --spp 16 --progress-gif -o progress.gif
 caustics preview scenes/weekend.rb --size 400x225 --spp 16 -o preview.png
 ~~~
 
+`--progress-gif` writes a cumulative frame after every sample. Install the optional [Flipbook](https://github.com/rbgfx/flipbook) gem to use it.
+
 Use the Ruby API directly:
 
 ~~~ruby
@@ -85,6 +93,10 @@ bundle install
 bundle exec rake verify
 ~~~
 
+## Contributing
+
+Bug reports and pull requests are welcome at [rbgfx/caustics](https://github.com/rbgfx/caustics).
+
 ## License
 
 [MIT](LICENSE.txt)

data/Rakefile

@@ -3,7 +3,7 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec) { |task| task.ruby_opts = ["-I../tessel/lib", "-I../rlsl/lib"] }
+RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
 task verify: :spec

data/docs/index.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="theme-color" content="#020617"><meta name="description" content="A pure Ruby path tracer and teaching example for cameras, materials, textures, and acceleration.">
+<meta property="og:title" content="Caustics — Follow the light."><meta property="og:description" content="A pure Ruby path tracer and teaching example for cameras, materials, textures, and acceleration."><meta property="og:type" content="website"><meta property="og:url" content="https://rbgfx.github.io/caustics/">
+<meta name="twitter:card" content="summary"><link rel="canonical" href="https://rbgfx.github.io/caustics/"><title>Caustics — Follow the light.</title>
+<style>
+:root{color-scheme:dark;--bg:#020617;--panel:#0f172a;--line:#334155;--ink:#e2e8f0;--muted:#94a3b8;--a:#38bdf8;--mono:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;--sans:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;--w:min(100% - 2.5rem,76rem)}
+*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.65 var(--sans)}a{color:inherit;text-underline-offset:.22em}a:hover{color:var(--a)}a:focus-visible{outline:3px solid var(--a);outline-offset:4px}h1,h2,h3,p,figure,pre{margin:0}h1,h2,h3{line-height:1.08;text-wrap:balance}p{text-wrap:pretty}code,pre,.mono{font-family:var(--mono);font-variant-numeric:tabular-nums}.wrap{width:var(--w);margin:auto}.skip{position:fixed;left:1rem;top:1rem;z-index:1;transform:translateY(-160%);padding:.7rem 1rem;background:var(--ink);color:var(--bg)}.skip:focus{transform:none}
+header{height:4.75rem;border-bottom:1px solid var(--line);display:flex;align-items:center;justify-content:space-between}.brand{display:flex;align-items:center;gap:.7rem;font-weight:750;text-decoration:none}.mark{width:2rem;height:2rem;display:grid;place-items:center;border:1px solid var(--a);color:var(--a);font:.85rem var(--mono)}nav{display:flex;gap:1.5rem;font-size:.9rem}nav a{text-decoration:none;color:var(--muted)}nav a:last-child{color:var(--ink)}
+.hero{display:grid;grid-template-columns:.88fr 1.12fr;align-items:center;gap:clamp(2rem,6vw,6rem);padding-block:clamp(4rem,9vw,8rem)}.kicker,.visual figcaption,.num{font:.76rem/1.4 var(--mono);color:var(--a)}h1{max-width:11ch;margin-top:1rem;font-size:clamp(3rem,7.5vw,6.5rem);letter-spacing:-.065em}.lede{max-width:40rem;margin-top:1.5rem;color:var(--muted);font-size:1.15rem}.actions{display:flex;flex-wrap:wrap;gap:.8rem;margin-top:2rem}.button{min-height:2.8rem;padding:.65rem 1rem;border:1px solid var(--line);display:inline-flex;align-items:center;text-decoration:none;font-weight:650}.button.primary{background:var(--a);border-color:var(--a);color:var(--bg)}.install{margin-top:1.4rem;color:var(--muted);font:.86rem var(--mono)}.install code{color:var(--ink)}
+.visual{border:1px solid var(--line);background:var(--panel)}.art{min-height:18rem;padding:1.25rem;display:grid;place-items:center;overflow:hidden}.art svg{width:100%;max-height:23rem}.visual figcaption{display:flex;justify-content:space-between;gap:1rem;padding:.75rem 1rem;border-top:1px solid var(--line);color:var(--muted)}.visual figcaption span:last-child{color:var(--a)}
+section.info{padding-block:4.5rem;border-top:1px solid var(--line)}.section-head{display:grid;grid-template-columns:.72fr 1.28fr;gap:2rem;align-items:end;margin-bottom:2rem}h2{font-size:clamp(2rem,4vw,3.25rem);letter-spacing:-.045em}.section-head p,.feature p,.try-copy p{color:var(--muted)}.features{display:grid;grid-template-columns:repeat(3,1fr);border-top:1px solid var(--line)}.feature{padding:1.25rem 1.2rem 1.4rem 0;border-bottom:1px solid var(--line)}.feature+.feature{padding-left:1.2rem;border-left:1px solid var(--line)}.feature h3{margin-top:.8rem;font-size:1.1rem}.feature p{margin-top:.5rem;font-size:.94rem}.try{display:grid;grid-template-columns:.75fr 1.25fr;align-items:center;gap:clamp(2rem,7vw,7rem)}.try-copy p{margin-top:1rem}.try-copy a{color:var(--ink)}pre{overflow-x:auto;padding:1.25rem;border:1px solid var(--line);background:var(--panel);font-size:.82rem;line-height:1.8;tab-size:2}
+footer{display:flex;justify-content:space-between;gap:1rem;padding-block:1.6rem;border-top:1px solid var(--line);color:var(--muted);font-size:.85rem}footer div{display:flex;gap:1.25rem}
+@media(max-width:800px){.hero{grid-template-columns:1fr;gap:2.5rem}.hero-copy{max-width:42rem}.section-head,.try{grid-template-columns:1fr;gap:1rem}}@media(max-width:560px){:root{--w:min(100% - 1.5rem,76rem)}header{height:4.2rem}nav{gap:.8rem;font-size:.8rem}nav a:first-child{display:none}h1{font-size:clamp(3rem,15vw,5rem)}.features{grid-template-columns:1fr}.feature,.feature+.feature{padding:1.1rem 0;border-left:0}.num{display:inline-block}footer{flex-direction:column}.art{min-height:14rem}section.info{padding-block:3.5rem}pre{font-size:.75rem;padding:1rem}}
+@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}}
+
+</style>
+</head><body style="--a:#f59e0b"><a class="skip" href="#main">Skip to content</a><div class="wrap">
+<header><a class="brand" href="#top" aria-label="Caustics home"><span class="mark" aria-hidden="true">C</span><span>Caustics</span></a><nav aria-label="Primary navigation"><a href="#features">Overview</a><a href="#quick-start">Quick start</a><a href="https://github.com/rbgfx/caustics">Source ↗</a></nav></header>
+<main id="main"><section class="hero" id="top" aria-labelledby="title"><div class="hero-copy"><p class="kicker">Deterministic path tracing · Ruby</p><h1 id="title">Follow the light.</h1><p class="lede">A pure Ruby path tracer and teaching example for cameras, materials, textures, and acceleration.</p><div class="actions"><a class="button primary" href="#quick-start">Get started</a><a class="button" href="https://rubygems.org/gems/caustics">RubyGems ↗</a></div><p class="install"><span aria-hidden="true">$</span> <code>gem install caustics</code></p></div>
+<figure class="visual" aria-labelledby="cap-caustics"><div class="art"><svg viewBox="0 0 640 360" aria-hidden="true"><rect width="640" height="360" fill="#0b1224"/><path d="M0 264H640" stroke="#334155"/><g stroke="#f59e0b" fill="none"><path d="M42 44L244 224M42 44L320 236M42 44L432 215M42 44L548 252M42 44L256 130M42 44L356 115"/></g><circle cx="240" cy="218" r="50" fill="#7c2d12" stroke="#fbbf24" stroke-width="3"/><circle cx="404" cy="239" r="75" fill="#1e293b" stroke="#94a3b8" stroke-width="2"/></svg></div><figcaption id="cap-caustics"><span>A scene, in rays</span><span>Ruby reference engine</span></figcaption></figure></section>
+<section class="info" id="features" aria-labelledby="feat"><div class="section-head"><h2 id="feat">A renderer you can inspect.</h2><p>Build scenes from small parts, render repeatable samples, and compare backends.</p></div><div class="features"><article class="feature"><span class="num">01</span><h3>Compose geometry</h3><p>Trace spheres, planes, triangles, and quads through a BVH.</p></article><article class="feature"><span class="num">02</span><h3>Work with materials</h3><p>Use Lambertian, metal, dielectric, emission, and image textures.</p></article><article class="feature"><span class="num">03</span><h3>Render repeatably</h3><p>Deterministic sampling, depth of field, and process workers where fork exists.</p></article></div></section>
+<section class="info try" id="quick-start" aria-labelledby="quick"><div class="try-copy"><p class="kicker">A small first step</p><h2 id="quick">Start with one example.</h2><p>Install the gem, then follow the project guide for platform requirements and the full API.</p><p><a href="https://github.com/rbgfx/caustics#installation">Read the installation guide ↗</a></p></div><pre><code>require &quot;caustics&quot;
+
+scene = Caustics::Scene.build do
+  sphere center: [0, 0, 0], radius: 0.5,
+         material: lambertian([0.8, 0.2, 0.2])
+end
+
+Caustics.render(scene, width: 320, height: 180,
+                spp: 16, workers: 4).write(&quot;out.png&quot;)</code></pre></section></main>
+<footer><span>Caustics · Ruby 3.1+ · MIT</span><div><a href="https://github.com/rbgfx/caustics">GitHub</a><a href="https://github.com/rbgfx/caustics/blob/main/LICENSE.txt">License</a></div></footer></div></body></html>

data/exe/caustics

@@ -6,29 +6,34 @@ require "caustics"
 
 command = ARGV.shift
 unless %w[render bench codegen preview].include?(command)
-  warn "usage: caustics render|bench|codegen|preview SCENE.rb [--size WxH] [--spp N] [--workers N] [--engine NAME,...] [-o FILE]"
+  warn "usage: caustics render|bench|codegen|preview SCENE.rb [--size WxH] [--spp N] [--workers N] [--engine NAME,...] [--progress-gif] [-o FILE]"
   exit 1
 end
 
 path = ARGV.shift
 raise ArgumentError, "scene file is required" unless path
 output = "out.png"
+output_explicit = false
 size = [400, 225]
 spp = 4
 workers = 1
 seed = 42
 max_depth = 8
 engines = [:ruby]
+progress_gif = false
 OptionParser.new do |options|
-  options.on("-o FILE") { |value| output = value }
+  options.on("-o FILE") { |value| output = value; output_explicit = true }
   options.on("--size SIZE") { |value| size = value.split("x").map(&:to_i) }
   options.on("--spp N", Integer) { |value| spp = value }
   options.on("--workers N", Integer) { |value| workers = value }
   options.on("--seed N", Integer) { |value| seed = value }
   options.on("--max-depth N", Integer) { |value| max_depth = value }
   options.on("--engine NAME") { |value| engines = value.split(",").map { |name| name.to_sym } }
+  options.on("--progress-gif") { progress_gif = true }
 end.parse!(ARGV)
 raise ArgumentError, "size must be WIDTHxHEIGHT" unless size.length == 2 && size.all?(&:positive?)
+raise ArgumentError, "spp, workers and max-depth must be positive" unless [spp, workers, max_depth].all?(&:positive?)
+raise ArgumentError, "--progress-gif is only valid with render" if progress_gif && command != "render"
 load path
 scene = defined?(SCENE) ? SCENE : $scene
 raise ArgumentError, "scene file must assign SCENE or $scene" unless scene
@@ -36,7 +41,26 @@ raise ArgumentError, "scene file must assign SCENE or $scene" unless scene
 case command
 when "render"
   raise ArgumentError, "render accepts one engine" unless engines.one?
-  Caustics.render(scene, width: size[0], height: size[1], spp: spp, max_depth: max_depth, workers: workers, seed: seed, engine: engines.first).write(output)
+  if progress_gif
+    output = "out.gif" unless output_explicit
+    raise ArgumentError, "--progress-gif output must end in .gif" unless File.extname(output).downcase == ".gif"
+    begin
+      require "flipbook"
+    rescue LoadError => error
+      raise LoadError, "caustics --progress-gif requires the optional flipbook gem", cause: error
+    end
+    accumulator = Caustics::Accumulator.new(size[0], size[1])
+    Flipbook::GIF::Writer.open(output, width: size[0], height: size[1], loop: true, palette: :per_frame) do |writer|
+      spp.times do
+        sample = Caustics.render(scene, width: size[0], height: size[1], spp: 1, max_depth: max_depth,
+                                 workers: workers, seed: seed + accumulator.samples, engine: engines.first)
+        writer.add(accumulator.add(sample), delay: Rational(1, 10))
+      end
+    end
+  else
+    Caustics.render(scene, width: size[0], height: size[1], spp: spp, max_depth: max_depth,
+                    workers: workers, seed: seed, engine: engines.first).write(output)
+  end
   puts output
 when "bench"
   results = Caustics.benchmark(scene, engines: engines, width: size[0], height: size[1], spp: spp, max_depth: max_depth)

data/lib/caustics/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Caustics
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caustics
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
-- ydah
+- Yudai Takada
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tessel
@@ -16,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
 description: A deterministic pure Ruby ray tracer used as an rbgfx teaching example.
 email:
 - t.yudai92@gmail.com
@@ -35,6 +42,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/index.html
 - docs/spikes.md
 - exe/caustics
 - lib/caustics.rb
@@ -48,6 +56,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/rbgfx/caustics
   source_code_uri: https://github.com/rbgfx/caustics/tree/main
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -62,7 +71,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: A small Ruby path tracer
 test_files: []