ra 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0132d533f2f492c3e1816a06c4e4ff8dbed1be99720685e503d7db1bd1f95169
-  data.tar.gz: 8a08e49e2fcd0b13369814633f44d7ae8eddd62364b56ff3b7d1dc067fda8d5e
+  metadata.gz: b56b6d752ce23d6484526702a0702d865bfad49f0209a40a8e597adf7a3c1b13
+  data.tar.gz: e45c8ddc28b1723f9e2a114386a2a0927026e9cf2cb54a38f438f3583d84710c
 SHA512:
-  metadata.gz: 700954bb31ae48227519b590f50ea0337c05a54896276dc0efcc84010385bd0d5373621c00788b5de8558f97f5cdc679ea48cfd584c45887d0c0175fd52279e4
-  data.tar.gz: 5fcf6251eff2401b4fde9a47ac4fcd2f05a8b69b81586bd433aa7d4bae52165fbc879ac209fd64bb3dc7bb65d4c350cc9cbecb40e44c3d92ba76abe433216300
+  metadata.gz: 0b2723e84ab6a64a4036615d298e733714838a754aecd59e0146eef97bd7b3c01374a3a9b4e145e9bb3ac437fe6499b41d819bf3fb79be92494bd2a2629c6f39
+  data.tar.gz: 1f74e78ddc9fbd2c61e231601d08519a8279279418ce8df0e8d6528a183412e09bbbfd138cbb3cd15fcb96979cac30b312520b3694b2c1232d394a1598dcfa57

data/README.md

@@ -1,31 +1,18 @@
 # Ra
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ra`. To experiment with that code, run `bin/console` for an interactive prompt.
+Named for [Ra](https://en.wikipedia.org/wiki/Ra) - arguably the original ray tracer.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```sh
+gem install ra
+```
 
 ## Usage
 
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
+```sh
+ra -w 2560 -h 2048 > sample.ppm
+convert -quality 80  sample.ppm sample.avif
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ra.
+![Sample](./sample.avif)

data/exe/ra

@@ -0,0 +1,130 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require 'ra'
+require 'slop'
+
+config = Slop.parse(ARGV) do |options|
+  options.banner = 'Usage: ra -w 2560 -h 2048 | convert - sample.avif'
+
+  options.integer '-w', '--width', 'width', default: 1280
+  options.integer '-h', '--height', 'height', default: 1024
+  options.integer '-fov', 'degrees', default: 60
+
+  options.on('--help', 'help') do
+    Ra.logger.log(options)
+    exit
+  end
+
+  options.on('--version', 'version') do
+    Ra.logger.log(Ra::VERSION)
+    exit
+  end
+end
+
+earth = Ra::Pattern::Texture.new(path: File.join(File.dirname(__FILE__), '..', 'textures/earth.avif'))
+
+light_l = Ra::Light.new(
+  position: Vector[+5, +7, -9, Ra::Tuple::POINT],
+  intensity: Ra::Color.uniform(0.4),
+)
+
+light_r = Ra::Light.new(
+  position: Vector[-5, +7, -9, Ra::Tuple::POINT],
+  intensity: Ra::Color.uniform(0.8),
+)
+
+camera = Ra::Camera.new(
+  w: config[:w],
+  h: config[:h],
+  fov: config[:fov] * Math::PI / 180,
+  transform: Ra::Transform.view(
+    from: Vector[0, +1.5, -5.0, Ra::Tuple::POINT],
+    to: Vector[0, 0, +1.0, Ra::Tuple::POINT],
+    up: Vector[0, 1, 0, Ra::Tuple::VECTOR],
+  ),
+)
+
+floor = Ra::Shape::Plane.new(
+  material: Ra::Material.new(base: Ra::Pattern::Checkers.new(
+    colors: [
+      Ra::Color.hex('#e2e8f0'),
+      Ra::Color.hex('#94a3b8'),
+    ],
+  )),
+)
+
+wall_l = Ra::Shape::Plane.new(
+  material: Ra::Material.new(base: Ra::Pattern::Stripes.new(
+    colors: [
+      Ra::Color.hex('#94a3b8'),
+      Ra::Color.hex('#475569'),
+    ],
+  )),
+  transform: Ra::Transform
+    .translate(0, 0, +5.0)
+    .rotate_y(-Math::PI / 4)
+    .rotate_x(Math::PI / 2),
+)
+
+wall_r = Ra::Shape::Plane.new(
+  material: Ra::Material.new(base: Ra::Pattern::Stripes.new(
+    colors: [
+      Ra::Color.hex('#94a3b8'),
+      Ra::Color.hex('#475569'),
+    ],
+  )),
+  transform: Ra::Transform
+    .translate(0, 0, +5.0)
+    .rotate_y(Math::PI / 4)
+    .rotate_x(Math::PI / 2),
+)
+
+sphere = Ra::Shape::Sphere.new(
+  material: Ra::Material.new(base: earth),
+  transform: Ra::Transform
+    .translate(0, +0.5, -2.0)
+    .rotate_y(Math::PI / 2)
+    .scale(0.5, 0.5, 0.5),
+)
+
+cube_l = Ra::Shape::Cube.new(
+  material: Ra::Material.new(base: Ra::Pattern::Gradient.new(
+    color_a: Ra::Color.hex('#f43f5e'),
+    color_b: Ra::Color.hex('#8b5cf6'),
+  )),
+  transform: Ra::Transform
+    .translate(+1.0, +0.3, -1.5)
+    .scale(0.3, 0.3, 0.3),
+)
+
+cube_r = Ra::Shape::Cube.new(
+  material: Ra::Material.new(base: Ra::Pattern::Gradient.new(
+    color_a: Ra::Color.hex('#84cc16'),
+    color_b: Ra::Color.hex('#f97316'),
+  )),
+  transform: Ra::Transform
+    .translate(-1.0, +0.3, -1.5)
+    .scale(0.3, 0.3, 0.3),
+)
+
+lights = [
+  light_l,
+  light_r,
+]
+
+shapes = [
+  floor,
+  wall_l,
+  wall_r,
+  sphere,
+  cube_l,
+  cube_r,
+].freeze
+
+world = Ra::World.new(lights:, shapes:)
+engine = Ra::Engine.new(camera:, world:)
+canvas = engine.render
+
+Ra.logger.log(canvas.ppm)

data/lib/ra/camera.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Ra
+  # A camera produces rays used to generate pixels. By convention, the camera
+  # is positioned at the point <x=0,y=0,z=0>. The rays target an imaginary
+  # screen that exists at z=-1. The x,y values visible on the screen depend on
+  # the FOV and the width / height of the desired image.
+  #
+  # A FOV represents the angel of the world visible to the camera. A default
+  # FOV is 90 degrees. This results in 2.0 by 2.0 of the world visible at z=-1.
+  #
+  # A bigger FOV increases what in the world is visible to the camera. When FOV
+  # is 120 degrees then ~3.5 by ~3.5 world view visible through z=-1.
+  #
+  # A smaller FOV decreases what in the world is visible to the camera. When FOV
+  # is 60 degrees then ~1.2 by ~1.2 world view is visible through z=-1.
+  #
+  # The visible world view is then split into pixels bsaed on the l / w of the
+  # desired screen. The pixel size is calculated using these l / w dimensions.
+  # The pixels are defined to be evenly spaced within the visible world.
+  #
+  # An example of a default 90 degree FOV and w=5 / h=4 results in pixels that
+  # are of size 0.4 (the greater of 2.0 / w=5 and 2.0 / h=4). With these
+  # dimensions rays are cast to the center of pixels evenly distrubted across
+  # the screen.
+  class Camera
+    attr_accessor :h, :w, :fov, :transform
+
+    DEFAULT_W = 1280
+    DEFAULT_H = 1024
+    DEFAULT_FOV = Math::PI / 3
+
+    # @param transform [Ra::Transform]
+    # @param h [Numeric]
+    # @param w [Numeric]
+    # @param fov [Numeric]
+    def initialize(transform: Transform::IDENTITY, h: DEFAULT_H, w: DEFAULT_W, fov: DEFAULT_FOV)
+      @transform = transform
+      @h = h
+      @w = w
+      @fov = fov
+    end
+
+    # @param x [Numeric]
+    # @param y [Numeric]
+    # @return [Ra::Ray]
+    def ray(x:, y:)
+      pixel = transform.inverse * Vector[world_x(x:), world_y(y:), -1, Tuple::POINT]
+      origin = transform.inverse * Vector[0, 0, 0, Tuple::POINT]
+
+      direction = (pixel - origin).normalize
+
+      Ray.new(origin:, direction:)
+    end
+
+    # @return [Float]
+    def p_size
+      @p_size ||= half_w * 2 / w
+    end
+
+    # @return [Float]
+    def half_view
+      @half_view ||= Math.tan(@fov / 2)
+    end
+
+    # @return [Float]
+    def half_w
+      @half_w ||= @w < @h ? (half_view * @w / @h) : half_view
+    end
+
+    # @return [Float]
+    def half_h
+      @half_h ||= @h < @w ? (half_view * @h / @w) : half_view
+    end
+
+    private
+
+    # @param y [Float]
+    # @return [Float]
+    def world_y(y:)
+      offset_y = (y + 0.5) * p_size
+      half_h - offset_y
+    end
+
+    # @param x [Float]
+    # @return [Float]
+    def world_x(x:)
+      offset_x = (x + 0.5) * p_size
+      half_w - offset_x
+    end
+  end
+end

data/lib/ra/canvas.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Ra
+  # A canvas is used to track pixels at <x,y> coordinates. It is given a w / h
+  # and on initialization allocates a w by h collection of pixels. For example,
+  # defining a basic black and white checkboard canvas with altering squares
+  # then saving as [PPM](https://netpbm.sourceforge.net/doc/ppm.html):
+  #
+  #   canvas = Ra::Canvas.new(w: 4, h: 5, precision: 15)
+  #   canvas.w.times do |x|
+  #     canvas.h.times do |y|
+  #       canvas[x,y] = (x + y) % 2 == 0 ? Ra::Color.black : Ra::Color.white
+  #     end
+  #   end
+  #   canvas.ppm
+  class Canvas
+    attr_accessor :w, :h, :precision
+
+    PPM_VERSION = 'P3'
+
+    # @param w [Integer]
+    # @param h [Integer]
+    # @param precision [Integer]
+    def initialize(w:, h:, precision: Color::PRECISION)
+      @w = w
+      @h = h
+      @precision = precision
+      @pixels = Array.new(w) { Array.new(h) }
+    end
+
+    # @param x [Integer]
+    # @param y [Integer]
+    def [](x, y)
+      raise ArgumentError, "x=#{x} cannot be negative" if x.negative?
+      raise ArgumentError, "y=#{y} cannot be negative" if y.negative?
+      raise ArgumentError, "x=#{x} must be < #{@w}" unless x < @w
+      raise ArgumentError, "y=#{y} must be < #{@h}" unless y < @h
+
+      @pixels[x][y] || Color.black
+    end
+
+    # @param x [Integer]
+    # @param y [Integer]
+    # @param color [Ra::Color]
+    def []=(x, y, color)
+      raise ArgumentError, "x=#{x} cannot be negative" if x.negative?
+      raise ArgumentError, "y=#{y} cannot be negative" if y.negative?
+      raise ArgumentError, "x=#{x} must be < #{@w}" unless x < @w
+      raise ArgumentError, "y=#{y} must be < #{@h}" unless y < @h
+
+      @pixels[x][y] = color
+    end
+
+    # @return [String]
+    def ppm
+      buffer = String.new(<<~PPM, encoding: 'ascii')
+        #{PPM_VERSION}
+        #{@w} #{@h}
+        #{@precision}
+      PPM
+
+      @h.times do |y|
+        @w.times do |x|
+          buffer << (self[x, y].ppm(precision: @precision)) << "\n"
+        end
+      end
+
+      buffer
+    end
+  end
+end

data/lib/ra/color.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Ra
+  # Color can be represented using r / g / b. Each component is assigned a
+  # number between 0.0 and 1.0. A color can also be converted for use when
+  # saving as [PPM](https://netpbm.sourceforge.net/doc/ppm.html).
+  #
+  #   color = Ra::Color.hex("#00FF00")
+  #   color.r == 0.0
+  #   color.g == 1.0
+  #   color.b == 0.0
+  #
+  #   color = Ra::Color.new(
+  #     r: 0.5,
+  #     g: 0.7,
+  #     b: 0.9,
+  #   )
+  #   color.ppm == "128 179 230"
+  class Color
+    attr_accessor :r, :g, :b
+
+    PRECISION = 255
+
+    # @param value [Array<Numeric,Numeric,Numeric>]
+    # @return [Ra::Color]
+    def self.[](value)
+      new(
+        r: value[0],
+        g: value[1],
+        b: value[2],
+      )
+    end
+
+    # @param value [String] e.g. "#336699"
+    # @return [Ra::Color]
+    def self.hex(value)
+      r, g, b = value.match(/^#(..)(..)(..)$/).captures.map(&:hex)
+
+      new(
+        r: Float(r) / PRECISION,
+        g: Float(g) / PRECISION,
+        b: Float(b) / PRECISION,
+      )
+    end
+
+    # @param value [Numeric] between 0.0 and 1.0
+    # @return [Ra::Color]
+    def self.uniform(value)
+      new(r: value, g: value, b: value)
+    end
+
+    # @return [Ra::Color]
+    def self.white
+      @white ||= uniform(1.0)
+    end
+
+    # @return [Ra::Color]
+    def self.black
+      @black ||= uniform(0.0)
+    end
+
+    # @param r [Numeric] between 0.0 and 1.0
+    # @param g [Numeric] between 0.0 and 1.0
+    # @param b [Numeric] between 0.0 and 1.0
+    def initialize(r: 0.0, g: 0.0, b: 0.0)
+      @r = r
+      @g = g
+      @b = b
+    end
+
+    # @param precision [Integer]
+    # @return [Integer]
+    def ppm(precision: PRECISION)
+      "#{r_val(precision:)} #{g_val(precision:)} #{b_val(precision:)}"
+    end
+
+    # Combine the r / g / b components (+). If `other` is `nil` return `self`.
+    #
+    # @param other [Ra::Color, nil]
+    # @return [Ra::Color]
+    def +(other)
+      return self if other.nil?
+
+      self.class.new(r: r + other.r, g: g + other.g, b: b + other.b)
+    end
+
+    # Combine the r / g / b components (-). If `other` is `nil` return `self`.
+    #
+    # @param other [Ra::Color, nil]
+    # @return [Ra::Color]
+    def -(other)
+      return self if other.nil?
+
+      self.class.new(r: r - other.r, g: g - other.g, b: b - other.b)
+    end
+
+    # @param other [Ra::Color, Numeric]
+    # @return [Ra::Color]
+    def *(other)
+      is_color = other.is_a?(self.class)
+      other_r = is_color ? other.r : other
+      other_g = is_color ? other.g : other
+      other_b = is_color ? other.b : other
+
+      self.class.new(
+        r: r * other_r,
+        g: g * other_g,
+        b: b * other_b,
+      )
+    end
+
+    # @param other [Ra::Color, Numeric]
+    # @return [Ra::Color]
+    def /(other)
+      is_color = other.is_a?(self.class)
+      other_r = is_color ? other.r : other
+      other_g = is_color ? other.g : other
+      other_b = is_color ? other.b : other
+
+      self.class.new(
+        r: r / other_r,
+        g: g / other_g,
+        b: b / other_b,
+      )
+    end
+
+    # @return [Boolean]
+    def ==(other)
+      r_val == other.r_val && g_val == other.g_val && b_val == other.b_val
+    end
+
+    protected
+
+    # @return [Integer]
+    def r_val(precision: PRECISION)
+      val(value: r, precision:)
+    end
+
+    # @return [Integer]
+    def g_val(precision: PRECISION)
+      val(value: g, precision:)
+    end
+
+    # @return [Integer]
+    def b_val(precision: PRECISION)
+      val(value: b, precision:)
+    end
+
+    private
+
+    # @param value [Numeric]
+    # @param precision [Integer]
+    # @return [Integer]
+    def val(value:, precision: PRECISION)
+      (value * precision).clamp(0, precision).round
+    end
+  end
+end

data/lib/ra/engine.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Ra
+  # An engine takes uses a world / camera to generate a canvas.
+  class Engine
+    PRECISION = 255
+
+    # @param world [Ra::World]
+    # @param camera [Ra::Camera]
+    def initialize(world:, camera:)
+      @world = world
+      @camera = camera
+    end
+
+    # @return [Ra::Canvas]
+    def render
+      Ra::Canvas.new(w: @camera.w, h: @camera.h, precision: PRECISION).tap do |canvas|
+        @camera.h.times do |y|
+          @camera.w.times do |x|
+            draw(x:, y:, canvas:)
+          end
+        end
+      end
+    end
+
+    private
+
+    # @param x [Integer]
+    # @param y [Integer]
+    # @param canvas [Ra::Canvas]
+    def draw(x:, y:, canvas:)
+      ray = @camera.ray(x:, y:)
+
+      intersections = @world.intersect(ray:)
+      intersection = Intersection.hit(intersections:)
+
+      canvas[x, y] = @world.color(intersection:) if intersection
+    end
+  end
+end

data/lib/ra/intersection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Ra
+  # An intersection tracks the time t at which a shape is intersected by a ray.
+  class Intersection
+    attr_accessor :t, :ray, :shape
+
+    # @param intersections Array<Ra::Intersection>
+    # @return [Ra::Intersection, nil]
+    def self.hit(intersections:)
+      hit = nil
+
+      intersections.each do |interaction|
+        next if interaction.t.negative?
+
+        hit = interaction if hit.nil? || interaction.t < hit.t
+      end
+
+      hit
+    end
+
+    # @param t [Numeric]
+    # @param ray [Ra::Ray]
+    # @param shape [Ra::Shape::Base]
+    def initialize(t:, ray:, shape:)
+      @t = t
+      @ray = ray
+      @shape = shape
+    end
+
+    # @return [Boolean]
+    def ==(other)
+      t == other.t && ray == other.ray && shape == other.shape
+    end
+
+    # @return [Ra::Surface]
+    def surface
+      point = ray.position(t:)
+      eyev = -ray.direction
+      normalv = shape.normal(point:)
+
+      Surface.new(shape:, eyev:, normalv:, point:)
+    end
+  end
+end

data/lib/ra/light.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Ra
+  # A light has a position within a scene and an intensity it is rendered
+  # with. For example:
+  #
+  #   light = Ra::Light.new(
+  #     intensity: Ra::Color.uniform(0.8),
+  #     position: Vector[0, 0, 0, Ra::Tuple::POINT],
+  #   )
+  class Light
+    attr_accessor :intensity, :position
+
+    # @param intensity [Ra::Color]
+    # @param position [Vector]
+    def initialize(intensity:, position:)
+      @intensity = intensity
+      @position = position
+    end
+  end
+end

data/lib/ra/lighting.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Ra
+  # Lighting encaspulates a [Phong Reflection Model](https://en.wikipedia.org/wiki/phong_reflection_model).
+  class Lighting
+    attr_accessor :light, :surface, :shadowed
+
+    # @param light [Ra::Light]
+    # @param surface [Ra::Surface]
+    # @param shadowed [Boolean]
+    def initialize(light:, surface:, shadowed:)
+      @surface = surface
+      @shadowed = shadowed
+      @light = light
+    end
+
+    # @return [Ra::Color]
+    def color
+      ambient_color + diffuse_color + specular_color
+    end
+
+    private
+
+    # @return [Ra::Shape]
+    def shape
+      surface.shape
+    end
+
+    # @return [Vector]
+    def point
+      surface.point
+    end
+
+    # @return [Vector]
+    def normalv
+      surface.normalv
+    end
+
+    # @return [Vector]
+    def eyev
+      surface.eyev
+    end
+
+    # @return [Ra::Material]
+    def material
+      shape.material
+    end
+
+    # @return [Ra::Vector]
+    def lightv
+      @lightv ||= (light.position - point).normalize
+    end
+
+    # @return [Ra::Vector]
+    def reflectv
+      @reflectv ||= -(lightv - (normalv * 2 * lightv.dot(normalv)))
+    end
+
+    # @return [Ra::Vector]
+    def light_dot_normal
+      @light_dot_normal ||= lightv.dot(normalv)
+    end
+
+    # @return [Ra::Vector]
+    def reflect_dot_eye
+      @reflect_dot_eye ||= reflectv.dot(eyev)
+    end
+
+    # @return [Ra::Color]
+    def ambient_color
+      @ambient_color ||= effective_color * material.ambient
+    end
+
+    # @return [Ra::Color, nil]
+    def diffuse_color
+      return if shadowed
+      return if light_dot_normal.negative?
+
+      @diffuse_color ||= effective_color * material.diffuse * light_dot_normal
+    end
+
+    # @return [Ra::Color, nil]
+    def specular_color
+      return if shadowed
+      return if light_dot_normal.negative?
+      return unless reflect_dot_eye.positive?
+
+      @specular_color ||= light.intensity * material.specular * (reflect_dot_eye**material.shininess)
+    end
+
+    # @return [Ra::Color]
+    def effective_color
+      @effective_color ||= shape.color(point:) * light.intensity
+    end
+  end
+end