jax-fractals 1.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in heightmap.gemspec
+gemspec

data/README.md

@@ -0,0 +1,124 @@
+# jax-fractals
+
+Fractal textures for [Jax](http://blog.jaxgl.com/what-is-jax)!
+
+[<img src="https://raw.github.com/sinisterchipmunk/jax-fractals/master/screenshots/hm.png" width="128" height="128">](https://github.com/sinisterchipmunk/jax-fractals/blob/master/screenshots/hm.png)
+[<img src="https://raw.github.com/sinisterchipmunk/jax-fractals/master/screenshots/1.png" width="128" height="128">](https://github.com/sinisterchipmunk/jax-fractals/blob/master/screenshots/1.png)
+[<img src="https://raw.github.com/sinisterchipmunk/jax-fractals/master/screenshots/3.png" width="128" height="128">](https://github.com/sinisterchipmunk/jax-fractals/blob/master/screenshots/3.png)
+[<img src="https://raw.github.com/sinisterchipmunk/jax-fractals/master/screenshots/4.png" width="128" height="128">](https://github.com/sinisterchipmunk/jax-fractals/blob/master/screenshots/4.png)
+
+## Why?
+
+Because I can! Also, fractals are oh-so-useful for terrain generation, cloud simulation, lava, and various other natural-looking effects.
+
+## Features
+
+* Adds a command-line generator for creating static fractal images
+  * Customizable options include random seed, image width, image height, and smoothness factor
+  * Defaults to a grayscale image, but can generate fractals using any color for low and high values
+  * Fractals which have power-of-two dimensions can be cleanly tiled
+  * Fractals can be generated with an alpha channel, which is helpful for rendering clouds
+  * Can generate "islands" -- that is, there are no high points on the borders
+* Adds a Heightmap model to Jax for processing fractal images into terrain
+  * Vertical scale can be set independently from width and depth scale
+  * Quickly calculates normals for the height map, for efficient lighting
+  * Returns interpolated height values for fractional coordinates
+  * Height maps whose width and depth are powers of two can be cleanly tiled for endless landscapes
+* For Rails projects, adds a controller for generating fractal images on-the-fly and caching them as appropriate
+
+## Dependencies
+
+This gem requires Jax and RMagick 2.
+
+## Installation
+
+Add the following to your Gemfile:
+
+    gem 'jax-fractals'
+
+Or, for the latest development version, the following:
+
+    gem 'jax-fractals', :git => "http://github.com/sinisterchipmunk/jax-fractals"
+
+Then type:
+
+    bundle install
+
+## Usage
+
+### The Generator
+
+The quickest way to get a fractal image into your app is to generate it from the command line:
+
+    rails generate fractal name-of-fractal
+    
+By default, it will have pixel dimensions 128x128, and will be generated with a smoothness factor of 2. You can customize all of these options:
+
+    rails generate fractal name-of-fractal --width=256 --height=256 --smoothness=1.25
+
+A different fractal image will be generated each time the generator is run unless a random seed is specified:
+
+    rails generate fractal name-of-fractal --seed=100
+    
+You can also change the colors for the low and high values, which default to black and white, respectively. The following example will replace black with red, and white with blue:
+
+    rails generate fractal name-of-fractal --low-color=ff0000 --high-color=0000ff
+    
+Sometimes you need the fractal to include an alpha (transparency) channel, so that the lower values are more transparent and the higher ones are more opaque. Simple!
+
+    rails generate fractal name-of-fractal --alpha
+
+Occasionally, you'll want to generate a fractal that is guaranteed to have intensity values equal to 0 along its borders. This is useful if you're generating a single cloud in the sky (as opposed to a tileable texture) or an island in the sea. To do this with the generator:
+
+    rails generate fractal name-of-fractal --island
+
+
+### The Controller
+
+To mount the fractal controller, add the following to your routes.rb file:
+
+    mount Fractal::Engine => "/fractals"
+
+Restart the Rails server, and you can generate a fractal by visiting its URL. There is a single required parameter, its ID, which is used as a random seed. You can also pass width, height, smoothness and color parameters.
+
+Experiment with the following examples:
+
+* [http://localhost:3000/fractals/1](http://localhost:3000/fractals/1)
+* [http://localhost:3000/fractals/2](http://localhost:3000/fractals/2)
+* [http://localhost:3000/fractals/2?island=1](http://localhost:3000/fractals/2?island=1)
+* [http://localhost:3000/fractals/2?low_color=ff0000&high_color=0000ff](http://localhost:3000/fractals/2?low_color=ff0000&high_color=0000ff)
+* [http://localhost:3000/fractals/2?low_color=ff0000&high_color=0000ff&alpha=true](http://localhost:3000/fractals/2?low_color=ff0000&high_color=0000ff&alpha=true)
+* [http://localhost:3000/fractals/1?width=256&height=256](http://localhost:3000/fractals/1?width=256&height=256)
+* [http://localhost:3000/fractals/1?smoothness=1.25](http://localhost:3000/fractals/1?smoothness=1.25)
+* [http://localhost:3000/fractals/1?width=256&height=256&smoothness=1.25](http://localhost:3000/fractals/1?width=256&height=256&smoothness=1.25)
+
+Once generated, fractals will be stored in the Rails cache, so that they only need to be generated one time. After generation, the cached copy will be returned instead.
+
+
+### The Heightmap
+
+Height maps will work with any image, not just fractals, but they play so nicely together that I couldn't resist adding the Heightmap model to this library.
+
+The easiest way to create a height map is to create a resource file. In your Rails or Jax project, create the file `app/assets/jax/resources/heightmaps/test.resource` and add the following information to it:
+
+    path: "/fractals/5"
+    xz_scale: 0.75
+    y_scale: 8.0
+    
+This will load the fractal dynamically from the Fractals controller (note: you have to change the path to reference a static image if you're not using Rails), scale its width and depth by 3/4, and then scale its height by 8 to produce a hilly (but not too mountainous!) terrain.
+
+If you want to texture it (and who wouldn't?), create a material like you'd create any other Jax material:
+
+    $ jax g material ground texture
+
+Then, set it in the resource file:
+
+    material: "ground"
+
+#### Actually Using It
+
+To add the "test" heightmap to the world, add it like you would any other Jax model instance. Do this in your Jax controller:
+
+    @world.addObject Heightmap.find "test"
+
+Done!

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/app/assets/jax/models/heightmap.js.coffee

@@ -0,0 +1,160 @@
+# Height map can be created in one of two ways. The most common is by referencing
+# a height image by its path:
+#
+#     hm = new HeightMap path: "/path/to/image.png"
+#
+# When loaded form an image, the height value for any given vertex is calculated
+# with the following formula, clamping the value between 0 and 1:
+#
+#     (red * 65536 + green * 256 + blue) / 16777215
+#
+# The height is then scaled by @y_scale, if given. Alpha values are ignored.
+# You can ignore this formula entirely if the image is an 8bpp grayscale.
+#
+# You can also set the @xz_scale to control the horizontal dimensions of the
+# height map.
+#
+#
+# The second method of instantiation is to specify height values explicitly
+# along with a width and depth. You can use nested arrays for this, for
+# organization, but a single flat array is also supported:
+#
+#     hm = new HeightMap
+#       width: 4
+#       depth: 2
+#       heights: [
+#         [ 0, 64, 128, 255 ],
+#         [ 255, 64, 128, 0 ]
+#       ]
+#
+#     hm = new HeightMap
+#       width: 4
+#       depth: 2
+#       heights: [
+#           0, 64, 128, 255,
+#         255, 64, 128,   0
+#       ]
+# 
+# Note that each height value must be a number between 0 and 255, and each
+# height value corresponds to a separate vertex (so, no worrying about RGBA).
+# The height values will be automatically scaled to a value between 0 and 1,
+# and then scaled again according to @y_scale, as with loading from an image.
+#
+RGB_SCALE = 1.0 / 16777215
+Jax.getGlobal()['Heightmap'] = Jax.Model.create
+  # Returns the height map value at the given X or Z offset. Values may be
+  # fractional. If the values are negative or if they exceed the width or
+  # depth of this height map, they will be wrapped. If they are fractional,
+  # then a suitable height value between the floor and ceiling of the values
+  # will be calculated.
+  #
+  # Examples:
+  #     hm = new Heightmap(width:2,depth:2,heights:[[0,1],[2,0]])
+  #     hm.height( 0  , 0   )    #=> 0
+  #     hm.height( 1  , 0   )    #=> 1
+  #     hm.height( 0  , 1   )    #=> 2
+  #     hm.height(-1  , 0   )    #=> 1
+  #     hm.height( 3  , 0   )    #=> 1
+  #     hm.height( 0.5, 0   )    #=> 0.5
+  #     hm.height( 0  , 0.75)    #=> 1.5
+  #
+  height: (x, z) ->
+    if @heights == undefined then return 0 # heightmap hasn't loaded yet
+
+    x %= @width
+    z %= @depth
+    x = @width + x if x < 0
+    z = @depth + z if z < 0
+
+    [fracX, fracZ] = [x % 1, z % 1]
+    x = Math.floor x if fracX
+    z = Math.floor z if fracZ
+    
+    p = (x+z*@width)*4
+    # read RGB, ignoring alpha
+    y = (@heights[p] * 65536 + @heights[p+1] * 256 + @heights[p+2]) * RGB_SCALE * @y_scale
+    return y unless fracX || fracZ
+    
+    [h, h2, h3, h4] = [y, @height(x+1, z)-y, @height(x, z+1)-y, @height(x+1,z+1)-y]
+    y = h2 * fracX + h3 * fracZ
+    if fracX && fracZ
+      y += (h4 + h2 - h3) * 0.5 * fracX
+      y += (h4 + h3 - h2) * 0.5 * fracZ
+      y /= 3
+    h + y
+    
+  after_initialize: ->
+    if @path
+      @img = new Image
+      @img.onload = =>
+        @loaded = true
+        c = document.createElement 'canvas'
+        [c.width, c.height] = [@img.width, @img.height]
+        c2d = c.getContext '2d'
+        c2d.drawImage @img, 0, 0
+        img = c2d.getImageData 0, 0, @img.width, @img.height
+        @width = img.width
+        @depth = img.height
+        @heights = img.data
+        @mesh.rebuild()
+      @img.src = @path
+    else if @width && @depth && @heights
+      heights = @heights
+      @heights = []
+      # modify data for RGBA compatibility
+      #
+      # this is a tradeoff -- slightly more memory for
+      # much faster image loading, since images will
+      # be much bigger and much more common. Note the only
+      # alternative is to iterate through each image pixel
+      # and convert it to a straight value, much like below,
+      # but way slower since images are bigger and more common.
+      for h in heights
+        if h instanceof Array
+          @heights.push v, v, v, v for v in h
+        else
+          @heights.push h, h, h, h
+      @loaded = true
+    else
+      throw new Error "Heightmap requires a path!"
+
+    @mesh = new Jax.Mesh
+      default_material: @material
+      draw_mode: GL_TRIANGLE_STRIP
+      init: (vertices, colors, texcoords, normals, indices) =>
+        if @loaded
+          # since we know some details about the map, this is much
+          # faster than the default Jax normal calcs, which must find
+          # and then average all adjacent face normals for any given
+          # vertex.
+          [r, l, t, b, h, v, n] = [vec3.create(),vec3.create(),vec3.create(),
+                                   vec3.create(),vec3.create(),vec3.create(),
+                                   vec3.create()]
+          calculateNormal = (x,z) =>
+            [r[0],r[1],r[2]] = [(x+1)*@xz_scale, @height(x+1,z), z*@xz_scale]
+            [l[0],l[1],l[2]] = [(x-1)*@xz_scale, @height(x-1,z), z*@xz_scale]
+            [t[0],t[1],t[2]] = [x*@xz_scale, @height(x,z+1), (z+1)*@xz_scale]
+            [b[0],b[1],b[2]] = [x*@xz_scale, @height(x,z-1), (z-1)*@xz_scale]
+            
+            vec3.normalize vec3.subtract r, l, h
+            vec3.normalize vec3.subtract t, b, v
+            vec3.normalize vec3.cross v, h, n
+            normals.push n[0], n[1], n[2]
+          
+          for x in [0..(@width-2)] by 2
+            index_base = vertices.length / 3
+            for z in [0..@depth]
+              indices.push index_base+z*3+1, index_base+z*3
+              vertices.push  x   *@xz_scale, @height(x  , z), z*@xz_scale
+              vertices.push (x+1)*@xz_scale, @height(x+1, z), z*@xz_scale
+              vertices.push (x+2)*@xz_scale, @height(x+2, z), z*@xz_scale
+              texcoords.push  x    / @width, z / @depth
+              texcoords.push (x+1) / @width, z / @depth
+              texcoords.push (x+2) / @width, z / @depth
+              calculateNormal x, z
+              calculateNormal x+1, z
+              calculateNormal x+2, z
+              
+            # reverse direction of z every other x, so triangle strip renders properly
+            for z in [(@depth)..0]
+              indices.push index_base+z*3+1, index_base+z*3+2

data/app/assets/jax/resources/heightmaps/default.resource

@@ -0,0 +1,4 @@
+# default attribute values
+# (these will apply to all heightmaps)
+xz_scale: 1
+y_scale: 1

data/app/controllers/fractal/fractals_controller.rb

@@ -0,0 +1,95 @@
+require_dependency 'fractal'
+
+class Fractal::FractalsController < ApplicationController
+  before_filter :set_default_parameters
+  before_filter :validate_dimensions
+  
+  # Fields:
+  #
+  #   id - the random seed for this fractal. Required.
+  #   width - the width of this fractal. Default: 128
+  #   height - the height of this fractal. Default: 128
+  #   smoothness - the smoothness of this fractal. Lower values produce more jagged / turbulent
+  #                results, higher values produce smoother results. Default: 2
+  #   high_color - the hex color code to use for high intensity values. Default: "ffffff"
+  #   low_color  - the hex color code to use for low intensity values. Default: "000000"
+  #   alpha      - if true, an alpha channel will be added. Lower intensity values will be more
+  #                transparent. Default: false
+  #   island     - if true, an "island" fractal will be generated, such that its borders are
+  #                guaranteed to have intensity values equal to 0. Default: false
+  #
+  def show
+    cache_key = File.join(params[:id], params[:width].to_s, params[:height].to_s,
+                          params[:smoothness].to_s, params[:alpha].to_s,
+                          params[:high_color].to_s, params[:low_color].to_s,
+                          params[:island].to_s)
+
+    unless data = Rails.cache.read(cache_key)
+      # The proc ensures that the image leaves scope prior to garbage collection,
+      # thus ensuring that it will actually be collected. This is all to prevent
+      # a memory leak, detailed here:
+      # http://rubyforge.org/forum/forum.php?thread_id=1374&forum_id=1618
+      proc {
+        image = generate_image
+        data = image.to_blob { self.format = 'PNG' }
+        image.destroy!
+      }.call
+      GC.start
+      
+      Rails.cache.write cache_key, data
+    end
+    
+    send_data data, :filename => "#{params[:id]}.png", :type => "image/png",
+                    :disposition => 'inline'
+  end
+
+  protected
+  def generate_image
+    Fractal::Generator.image(params.merge(:seed => params[:id].to_i))
+  end
+  
+  def set_default_parameters
+    params[:width]  = params[:width].blank?  ? default_dimensions[:width]  : params[:width].to_i
+    params[:height] = params[:height].blank? ? default_dimensions[:height] : params[:height].to_i
+    params[:smoothness] = params[:smoothness].blank? ? 2 : params[:smoothness].to_f
+    params[:smoothness] = 2 if params[:smoothness] <= 0
+    params[:alpha] = false unless params.key?(:alpha)
+    params[:island] = false unless params.key?(:island)
+  end
+  
+  def default_dimensions
+    { :width => 128, :height => 128 }
+  end
+  
+  def validate_dimensions
+    if (requested_width = params[:width]) > Fractal.max_size
+      params[:width] = Fractal.max_size
+      log = true
+    end
+    if (requested_height = params[:height]) > Fractal.max_size
+      params[:height] = Fractal.max_size
+      log = true
+    end
+    if log
+      logger.warn <<-end_warning
+      Requested dimensions #{requested_width}x#{requested_height} exceed maximum size
+      #{Fractal.max_size}x#{Fractal.max_size}. If you need a larger fractal,
+      create a file called config/initializers/fractals.rb and set
+      
+        Fractal.max_size = [some acceptable number]
+        
+      Or, set
+      
+        Fractal.max_size = nil
+        
+      ...to remove limits altogether (not recommended, as large fractals
+      can take a long time to generate!)
+      
+      The safest way to use very large fractals is just to preprocess them:
+      
+        rails g fractal
+        
+      end_warning
+    end
+  end
+end

data/jax-fractals.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "fractal/version"
+
+Gem::Specification.new do |s|
+  s.name        = "jax-fractals"
+  s.version     = Fractal::VERSION
+  s.authors     = ["Colin MacKenzie IV"]
+  s.email       = ["sinisterchipmunk@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Adds a fractal generator, and corresponding controller for Jax projects}
+  s.description = %q{Adds a fractal generator, and corresponding controller for Jax projects. Also adds a Heightmap model for Jax.}
+
+  s.rubyforge_project = "jax-fractals"
+  
+  s.add_dependency 'jax', '~> 2.0.6'
+  s.add_dependency 'rmagick', '~> 2.13.1'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/core_ext/math.rb

@@ -0,0 +1,23 @@
+class Fixnum
+  def pot?
+    (self & (self - 1)) == 0
+  end
+end
+
+module Math
+  module_function
+  
+  def max(a, b)
+    a > b ? a : b
+  end
+
+  def min(a, b)
+    a > b ? b : a
+  end
+  
+  def pot(x)
+    pot = 1
+    pot *= 2 until pot >= x
+    pot
+  end
+end

data/lib/fractal.rb

@@ -0,0 +1,22 @@
+begin
+  require 'rmagick'
+rescue LoadError
+  raise "RMagick not found! Make sure `gem 'rmagick', '~> 2.13.1'` is in your Gemfile"
+end
+
+require File.expand_path('core_ext/math', File.dirname(__FILE__))
+
+module Fractal
+  require File.expand_path("fractal/engine", File.dirname(__FILE__))
+
+  autoload :Map,       File.expand_path("fractal/map",       File.dirname(__FILE__))
+  autoload :Generator, File.expand_path("fractal/generator", File.dirname(__FILE__))
+  autoload :Version,   File.expand_path("fractal/version",   File.dirname(__FILE__))
+  autoload :IslandGenerator, File.expand_path('fractal/island_generator', File.dirname(__FILE__))
+  
+  class << self
+    attr_accessor :max_size
+  end
+  
+  self.max_size = 1024
+end

data/lib/fractal/engine.rb

@@ -0,0 +1,10 @@
+require 'rails'
+
+class Fractal::Engine < Rails::Engine
+  engine_name "fractals"
+  isolate_namespace Fractal
+  
+  routes do
+    match "/:id", :controller => "fractals", :action => "show"
+  end
+end

data/lib/fractal/generator.rb

@@ -0,0 +1,146 @@
+class Fractal::Generator
+  class << self
+    def image(options = {})
+      options.reverse_merge! default_image_options
+      klass = options[:island] ? Fractal::IslandGenerator : self
+      
+      fractal = klass.new options
+                    
+      if options[:alpha]
+        image = Magick::Image.new(fractal.width, fractal.height) { self.background_color = 'transparent' }
+        image.import_pixels 0, 0, fractal.width, fractal.height, 'IA', fractal.bytes.collect { |b| [b,b] }.flatten.pack('C*')
+      else
+        image = Magick::Image.new(fractal.width, fractal.height)
+        image.import_pixels 0, 0, fractal.width, fractal.height, 'I', fractal.bytes.pack('C*')
+      end
+      
+      options[:low_color] = '000000' if options[:low_color].blank?
+      options[:high_color] = 'ffffff' if options[:high_color].blank?
+      image = image.level_colors("##{options[:low_color]}", "##{options[:high_color]}", true)
+      image
+    end
+    
+    def default_image_options
+      { :alpha => false, :island => false, :high_color => 'ffffff', :low_color => '000000' }
+    end
+  end
+  
+  INITIAL_RANGE = 400
+  include Math
+  attr_reader :map, :random, :smoothness, :seed
+  
+  def width;  map.width;  end
+  def height; map.height; end
+  def bytes;  map.bytes;  end
+  
+  def initialize(options = {})
+    options.reverse_merge! default_options
+    width, height = options[:width], options[:height]
+    @map = Fractal::Map.new(pot(max(width, height)) + 1)
+    @random = options[:seed] ? Random.new(options[:seed]) : Random.new
+    @seed = @random.seed
+    @smoothness = options[:smoothness] || 2
+    generate
+    @map.truncate(width, height)
+  end
+  
+  def to_s
+    "".tap do |result|
+      for x in 0...width
+        for y in 0...height
+          result.concat map[x, y].to_s[0..6].rjust(7)
+          result.concat " "
+        end
+        result.concat "\n"
+      end
+    end
+  end
+
+  protected
+  def default_options
+    {
+      :width => 128,
+      :height => 128,
+      :smoothness => 2
+    }
+  end
+  
+  # Seed initial values, then return [step, range]
+  def sow_seeds
+    map[      0,        0] ||= 128
+    map[      0, height-1] ||= 128
+    map[width-1,        0] ||= 128
+    map[width-1, height-1] ||= 128
+
+    [width - 1, INITIAL_RANGE]
+  end
+  
+  def compute(x, y, points, range)
+    c = map[x, y] || 0
+    4.times do |i|
+      if points[i][0] < 0 then points[i][0] += (width - 1)
+      elsif points[i][0] > width then points[i][0] -= (width - 1)
+      elsif points[i][1] < 0 then points[i][1] += (height - 1)
+      elsif points[i][1] > height then points[i][1] -= (height - 1)
+      end
+      c += map[points[i][0], points[i][1]] * 0.25
+    end
+    
+    c += random.rand() * range - range / 2.0
+    if c < 0 then c = 0
+    elsif c > 255 then c = 255
+    end
+    
+    c = c.to_i
+    map[x, y] = c
+    if x == 0 then map[width-1, y] = c
+    elsif x == width-1 then map[0, y] = c
+    elsif y == 0 then map[x, height-1] = c
+    elsif y == height-1 then map[x, 0] = c
+    end
+  end
+
+  private
+  def half(step)
+    step >> 1
+  end
+  
+  def diamond(step, range)
+    halfstep = half step
+    (0...(width-1)).step step do |x|
+      (0...(height-1)).step step do |y|
+        sx = x + halfstep
+        sy = y + halfstep
+        points = [ [x, y], [x+step, y], [x, y+step], [x+step, y+step] ]
+        compute sx, sy, points, range
+      end
+    end
+  end
+  
+  def square(step, range)
+    halfstep = half step
+    (0...(width-1)).step step do |x|
+      (0...(height-1)).step step do |y|
+        x1 = x + halfstep
+        y1 = y
+        x2 = x
+        y2 = y + halfstep
+        points1 = [ [x1 - halfstep, y1], [x1, y1 - halfstep], [x1 + halfstep, y1], [x1, y1 + halfstep] ]
+        points2 = [ [x2 - halfstep, y2], [x2, y2 - halfstep], [x2 + halfstep, y2], [x2, y2 + halfstep] ]
+        compute x1, y1, points1, range
+        compute x2, y2, points2, range
+      end
+    end
+  end
+  
+  def generate
+    step, range = *sow_seeds
+    
+    while step > 1
+      diamond step, range
+      square step, range
+      range /= smoothness
+      step >>= 1
+    end
+  end
+end

data/lib/fractal/island_generator.rb

@@ -0,0 +1,32 @@
+# Generates fractals which are guaranteed to have border pixels set to 0
+class Fractal::IslandGenerator < Fractal::Generator
+  protected
+  def sow_seeds
+    step, range = *super
+    map[      0,        0] = 0
+    map[      0, height-1] = 0
+    map[width-1,        0] = 0
+    map[width-1, height-1] = 0
+    
+    # we can multiply range by 2 to maintain brightness
+    # because we are effectively cutting area in half by
+    # setting borders to 0 -- we must do this if we want
+    # max brightness == 255, instead of 128
+    [step, range*2]
+  end
+  
+  def compute(x, y, points, range)
+    # set borders to 0, but center to 128
+    if x == (width-1)/2 && y == (width-1/2)
+      map[x, y] = 128
+    elsif x == 0 || x == width-1
+      map[0, y] = 0
+      map[width-1, y] = 0
+    elsif y == 0 || y == height-1
+      map[x, 0] = 0
+      map[x, height-1] = 0
+    else
+      super
+    end
+  end
+end

data/lib/fractal/map.rb

@@ -0,0 +1,49 @@
+class Fractal::Map < Array
+  attr_accessor :width, :height
+  alias :row :[]
+  
+  class Line < Array
+    def initialize(count)
+      super count, nil
+    end
+    
+    def [](a)
+      if a.kind_of?(Numeric)
+        raise "Out of bounds: #{a} / #{length}" if a < 0 || a >= length
+      end
+      super
+    end
+    
+    def []=(a, *)
+      raise "Out of bounds: #{a} / #{length}" if a < 0 || a >= length
+      super
+    end
+  end
+  
+  def initialize(size)
+    @width = @height = size
+    super(size) { Fractal::Map::Line.new(size) }
+  end
+  
+  def truncate(width, height)
+    pop while length > height
+    collect! { |line| line[0...width] }
+    @width, @height = width, height
+  end
+  
+  def [](x, y)
+    raise "Out of bounds: #{y} / #{@height}" if y < 0 || y >= @height
+    super(y)[x]
+  end
+  
+  def []=(x, y, value)
+    row(y)[x] = value
+  end
+  
+  # Encodes the map as a grayscale bitmap, with a color depth of 8 bits per pixel.
+  #
+  # Returns the bitmap as an array of bytes.
+  def bytes
+    flatten.pack("C*").bytes.to_a
+  end
+end

data/lib/fractal/version.rb

@@ -0,0 +1,10 @@
+module Fractal
+  module Version
+    MAJOR = 1
+    MINOR = 0
+    TINY = 0
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+  
+  VERSION = Version::STRING
+end

data/lib/generators/fractal/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generates a fractal image in public/images/fractals.
+
+Example:
+    rails generate fractal clouds
+
+    This will create:
+        public/images/fractals/clouds

data/lib/generators/fractal/fractal_generator.rb

@@ -0,0 +1,18 @@
+require 'fractal'
+
+class FractalGenerator < Rails::Generators::NamedBase
+  class_option :seed, :default => nil, :desc => "Random seed for the fractal", :type => :numeric
+  class_option :width, :default => 128, :desc => "Width of the fractal image in pixels", :type => :numeric
+  class_option :height, :default => 128, :desc => "Height of the fractal image in pixels", :type => :numeric
+  class_option :smoothness, :default => 2, :desc => "Smoothness factor (higher is smoother)", :type => :numeric
+  class_option :dest, :default => "app/assets", :desc => "Where to place generated fractal", :type => :string
+  class_option :high_color, :default => 'ffffff', :desc => "Color to use for high intensity values", :type => :string
+  class_option :low_color, :default => '000000', :desc => "Color to use for low intensity values", :type => :string
+  class_option :alpha, :default => false, :desc => "Whether to save transparency data", :type => :boolean
+  class_option :island, :default => false, :desc => "Whether the borders should be guaranteed to have 0 intensity", :type => :boolean
+  
+  def generate_fractal
+    create_file File.join(options[:dest], 'images/fractals', "#{name}.png"),
+                Fractal::Generator.image(options).to_blob { self.format = 'PNG' }
+  end
+end

data/lib/jax-fractals.rb

@@ -0,0 +1 @@
+require File.expand_path('fractal', File.dirname(__FILE__))

data/spec/javascripts/jax/models/heightmap_spec.js.coffee

@@ -0,0 +1,67 @@
+describe "Heightmap", ->
+  model = null
+  
+  describe "while still loading", ->
+    beforeEach -> 
+      model = new Heightmap(path: "/fractals/1")
+    
+    it "should return height 0", ->
+      expect(model.heights(5, 5)).toEqual 0
+  
+  describe "loaded from a path", ->
+    beforeEach ->
+      model = new Heightmap(path: "/fractals/1")
+    
+    it "should load the model", ->
+      waitsFor -> model.loaded
+      
+  describe "with RGB, not grayscale", ->
+    beforeEach ->
+      model = new Heightmap(width: 1, depth: 1, heights: [[1]], y_scale: 16777215)
+      # HACK no good way to do this, but really it's not meant to be done
+      model.heights[0] = 1 # R
+      model.heights[1] = 2 # G
+      model.heights[2] = 3 # B
+      model.heights[3] = 4 # A
+      
+    it "should sample RGB and ignore A", ->
+      expected_height = 1 * 65536 + 2 * 256 + 3 # RGB, ignoring A
+      expect(model.height(0, 0)).toEqual expected_height
+  
+  describe "defined in-line", ->
+    beforeEach ->
+      model = new Heightmap(width: 4, depth: 2, heights: [ [ 0, 4, 0, 0 ], [2, 3, 0, 0] ], y_scale: 255)
+  
+    it "should return the expected height data", ->
+      expect(model.height(0, 0)).toEqual 0
+      expect(model.height(1, 0)).toEqual 4
+      expect(model.height(2, 0)).toEqual 0
+      expect(model.height(3, 0)).toEqual 0
+      expect(model.height(0, 1)).toEqual 2
+      expect(model.height(1, 1)).toEqual 3
+      expect(model.height(2, 1)).toEqual 0
+      expect(model.height(3, 1)).toEqual 0
+  
+    it "should wrap height indices out of bounds", ->
+      # X
+      expect(model.height(-3, 0)).toEqual 4
+      expect(model.height(-7, 0)).toEqual 4
+      expect(model.height( 5, 0)).toEqual 4
+      expect(model.height( 9, 0)).toEqual 4
+      # Z
+      expect(model.height(0, -1)).toEqual 2
+      expect(model.height(0, -3)).toEqual 2
+      expect(model.height(0,  2)).toEqual 0
+      expect(model.height(0,  3)).toEqual 2
+      expect(model.height(0,  4)).toEqual 0
+      
+    it "should compensate for fractional X,Z components", ->
+      expect(model.height(0.5, 0)).toEqual 2
+      expect(model.height(0,   0.5)).toEqual 1
+      expect(model.height(0.5, 0.5)).toEqual 1.5
+      
+      # Proximity -- should return approximately the same as x+1/z+1
+      expect(model.height(0.99999999, 0)).toBeGreaterThan 4-Math.EPSILON
+      expect(model.height(0, 0.99999999)).toBeGreaterThan 2-Math.EPSILON
+      expect(model.height(0.99999999, 0.99999999)).toBeGreaterThan 3-Math.EPSILON
+      

data/spec/lib/fractal/generator_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Fractal::Generator do
+  it "should truncate map by default" do
+    subject = Fractal::Generator.new(:width => 10, :height => 10)
+    subject.width.should == 10
+    subject.height.should == 10
+    subject.map.length.should == 10
+    subject.map.row(0).length.should == 10
+  end
+end

data/spec/lib/fractal/images_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe "Fractal images" do
+  def subject(options = {})
+    Fractal::Generator.image(options.reverse_merge(:seed => 1)).to_blob { self.format = 'PNG' }
+  end
+  
+  it "should generate default image" do
+    subject.should == fractal('1')
+  end
+  
+  it "should generate with alpha" do
+    subject(:alpha => true).should == fractal('1?alpha=1')
+  end
+  
+  it "should truncate size" do
+    subject(:width => 126, :height => 130).should == fractal('1?width=126&height=130')
+  end
+  
+  it "should generate an island" do
+    subject(:island => true).should == fractal('1?island=1')
+  end
+  
+  it "should generate more jagged fractals" do
+    subject(:smoothness => 1.2).should == fractal('1?smoothness=1.2')
+  end
+  
+  it "should set high color" do
+    subject(:high_color => 'ff0000').should == fractal('1?high_color=ff0000')
+  end
+  
+  it "should set low color" do
+    subject(:low_color => '0000ff').should == fractal('1?low_color=0000ff')
+  end
+  
+  it "should set high and low color" do
+    subject(:high_color => 'ff0000', :low_color => '0000ff').should == fractal('1?low_color=0000ff&high_color=ff0000')
+  end
+end

data/spec/lib/fractal/map_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe Fractal::Map do
+  subject { Fractal::Map.new(32) }
+  
+  it "should have size 32x32" do
+    subject.width.should == 32
+    subject.height.should == 32
+  end
+  
+  it "should have 32x32 elements" do
+    subject.flatten.length.should == 32*32
+  end
+  
+  it "should restrict bounds to 32x32" do
+    proc { subject[32, 0]     }.should raise_error
+    proc { subject[32, 0] = 1 }.should raise_error
+    proc { subject[0, 32]     }.should raise_error
+    proc { subject[0, 32] = 1 }.should raise_error
+  end
+  
+  it "should not allow assignment to first dimension" do
+    proc { subject[0] = [] }.should raise_error
+  end
+  
+  it "should truncate size" do
+    subject.truncate 10, 15
+    subject.width.should == 10
+    subject.height.should == 15
+    subject.length.should == 15
+    subject.row(0).length.should == 10
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$:.unshift File.expand_path('../lib', File.dirname(__FILE__))
+require 'jax-fractals'
+
+module Fixtures
+  def fractal(name)
+    File.read(File.expand_path(File.join("fixtures/fractals", name), File.dirname(__FILE__))).force_encoding('BINARY')
+  end
+end
+
+RSpec.configure do |c|
+  c.include Fixtures
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification 
+name: jax-fractals
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Colin MacKenzie IV
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-08 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: jax
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.0.6
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rmagick
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.13.1
+  type: :runtime
+  version_requirements: *id002
+description: Adds a fractal generator, and corresponding controller for Jax projects. Also adds a Heightmap model for Jax.
+email: 
+- sinisterchipmunk@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- app/assets/jax/models/heightmap.js.coffee
+- app/assets/jax/resources/heightmaps/default.resource
+- app/controllers/fractal/fractals_controller.rb
+- jax-fractals.gemspec
+- lib/core_ext/math.rb
+- lib/fractal.rb
+- lib/fractal/engine.rb
+- lib/fractal/generator.rb
+- lib/fractal/island_generator.rb
+- lib/fractal/map.rb
+- lib/fractal/version.rb
+- lib/generators/fractal/USAGE
+- lib/generators/fractal/fractal_generator.rb
+- lib/jax-fractals.rb
+- screenshots/1.png
+- screenshots/3.png
+- screenshots/4.png
+- screenshots/hm.png
+- spec/fixtures/fractals/1
+- spec/fixtures/fractals/1?alpha=1
+- spec/fixtures/fractals/1?high_color=ff0000
+- spec/fixtures/fractals/1?island=1
+- spec/fixtures/fractals/1?low_color=0000ff
+- spec/fixtures/fractals/1?low_color=0000ff&high_color=ff0000
+- spec/fixtures/fractals/1?smoothness=1.2
+- spec/fixtures/fractals/1?width=126&height=130
+- spec/javascripts/jax/models/heightmap_spec.js.coffee
+- spec/lib/fractal/generator_spec.rb
+- spec/lib/fractal/images_spec.rb
+- spec/lib/fractal/map_spec.rb
+- spec/spec_helper.rb
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: jax-fractals
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Adds a fractal generator, and corresponding controller for Jax projects
+test_files: 
+- spec/fixtures/fractals/1
+- spec/fixtures/fractals/1?alpha=1
+- spec/fixtures/fractals/1?high_color=ff0000
+- spec/fixtures/fractals/1?island=1
+- spec/fixtures/fractals/1?low_color=0000ff
+- spec/fixtures/fractals/1?low_color=0000ff&high_color=ff0000
+- spec/fixtures/fractals/1?smoothness=1.2
+- spec/fixtures/fractals/1?width=126&height=130
+- spec/javascripts/jax/models/heightmap_spec.js.coffee
+- spec/lib/fractal/generator_spec.rb
+- spec/lib/fractal/images_spec.rb
+- spec/lib/fractal/map_spec.rb
+- spec/spec_helper.rb