quad_sphere 0.9.0 → 1.0.0

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2012 Cesar Rincon <crincon@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,153 @@
+QuadSphere
+==========
+
+QuadSphere is a small Ruby gem that implements a projection of
+spherical to planar coordinates, called the _quadrilateralised
+spherical cube_.  It is useful for handling geographic or astronomical
+data, or for general mapmaking.
+
+![Sphere picture][9] ![Grid picture][10]
+
+Background
+----------
+
+The quadrilateralised spherical cube, or "quad sphere" for short, is a
+projection of the sphere onto the sides of an inscribed cube, where
+the distortion of the tangential (gnomonic) projection is compensated
+by a further curvilinear transformation.  This makes it approximately
+equal-area, with no singularities at the poles, or anywhere;
+distortion is moderate over the entire sphere.  This makes it
+well-suited for storing data collected on a spherical surface, like
+the Earth or the celestial sphere, as rasters of pixels: each
+equal-area pixel then corresponds to an equal-area region on the
+sphere, so numerical analysis can be performed on the pixels rather
+than the original surface.
+
+This projection was proposed in 1975 in the report "Feasibility Study
+of a Quadrilateralized Spherical Cube Earth Data Base", by F. K. Chan
+and E. M. O'Neill ([citation entry][6]), and it was used to hold data
+for the Cosmic Background Explorer project (COBE).  The quad sphere,
+along with a binning scheme for storing pixels along a Z-order curve,
+became the [COBE Sky Cube][1] format.
+
+This is not a Sky Cube reader, though — neither the binning scheme nor
+the FITS format are implemented here.  You should use a [FITS][5] library
+if you need to read COBE data.  And, for current astronomical work,
+the quadrilateralised spherical cube projection has been superseded by
+[HEALPix][3], so you should use that instead.  This implementation was
+only created because this author had a very specific need involving
+storage and manipulation of spherical data — for a game, no less.
+
+Note also that this is _not_ the projection by Laubscher and O'Neill,
+1976, which is similar to this but introduces singularities, making it
+non-differentiable along the diagonals.
+
+As Chan's original report is not readily available, this
+implementation is based on formulae found in [FITS WCS documents][2].
+Specifically: "Representations of celestial coordinates in FITS (Paper
+II)", Calabretta, M. R., and Greisen, E. W., _Astronomy &
+Astrophysics_, 395, 1077-1122, 2002.
+
+Finally, bear in mind that this is not an exact projection, it's
+accuracy is limited — see discussion in the documentation of
+[`QuadSphere::CSC.forward_distort`][8].
+
+Examples
+--------
+
+The basic usage, for converting a tuple of spherical coordinates (φ,θ)
+to cartesian (x,y) on a cube face, is:
+
+    require 'quad_sphere/csc'
+    face, x, y = QuadSphere::CSC.forward(phi, theta)
+
+Parameters `phi` and `theta` should be given in radians. `phi` is the
+azimuthal angle, or longitude; you'll want to make it something
+between -π and π (or 0 and 2π, if you like).  `theta` is the elevation
+angle, or (geocentric) latitude, so it should be between -π/2 and π/2.
+The values returned are: a face identifier (see constants in module
+[QuadSphere][11]), and cartesian (x,y), with each coordinate between
+-1 and 1.
+
+The inverse transfomation looks, not very surprisingly, like this:
+
+    lon, lat = QuadSphere::CSC.inverse(face, x, y)
+
+With all symbols meaning the same as before.
+
+As a more practical example, suppose you're storing geographic data in
+six bitmaps of 100x100 pixels each.  The following function will give
+you the bitmap and specific coordinates of the pixel where you should
+store a given latitude and longitude.
+
+    def geographic_to_storage_bin(latitude, longitude)
+      # Convert both angles to radians.
+      latitude = latitude*Math::PI/180
+      longitude = longitude*Math::PI/180
+
+      # Geographic latitudes are normally geodetic; we convert this to
+      # geocentric because we want spherical coordinates.  The magic
+      # number below is the Earth's eccentricity, squared, using the WGS84
+      # ellipsoid.
+      latitude = Math.atan((1 - 6.69437999014e-3) * Math.tan(latitude))
+
+      # Apply the forward transformation...
+      face, x, y = QuadSphere::CSC.forward(longitude, latitude)
+
+      # ... then adjust x and y so they become integer coordinates on a
+      # 100x100 grid, with 0,0 being top-left, as used in pictures.
+      x = (100*(1+x)/2).floor
+      y = 99 - (100*(1+y)/2).floor
+
+      # And return the computed values.
+      [ face, x, y ]
+    end
+
+Trying the above on a few locations on Earth:
+
+    [ [ 'Accra',          5.5500,   -0.2167 ],
+      [ 'Buenos Aires', -34.6036,  -58.3817 ],
+      [ 'Cairo',         30.0566,  -31.2262 ],
+      [ 'Honolulu',      21.3069, -157.8583 ],
+      [ 'Kuala Lumpur',   3.1597,  101.7000 ],
+      [ 'London',        51.5171,   -0.1062 ],
+      [ 'Longyearbyen',  78.216667, 15.55   ],
+      [ 'New Delhi',     28.6667,   77.2167 ],
+      [ 'New York',      40.7142,  -74.0064 ],
+      [ 'Quito',         -0.2186,  -78.5097 ],
+      [ 'Sydney',       -33.8683,  151.2086 ],
+      [ 'Ushuaia',      -54.8000,  -68.3000 ] ].each do |city, lat, lon|
+      face, x, y = geographic_to_storage_bin(lat, lon)
+      puts '%-12s - bitmap %d, x=%2d, y=%2d' % [city, face, x, y]
+    end
+
+Gives you:
+
+    Accra        - bitmap 1, x=49, y=43
+    Buenos Aires - bitmap 4, x=85, y=93
+    Cairo        - bitmap 1, x=14, y=11
+    Honolulu     - bitmap 3, x=76, y=23
+    Kuala Lumpur - bitmap 2, x=63, y=46
+    London       - bitmap 0, x=49, y=93
+    Longyearbyen - bitmap 0, x=53, y=63
+    New Delhi    - bitmap 2, x=35, y=16
+    New York     - bitmap 4, x=67, y= 3
+    Quito        - bitmap 4, x=63, y=50
+    Sydney       - bitmap 3, x=17, y=92
+    Ushuaia      - bitmap 5, x=11, y=32
+
+See more code in the `examples` directory, including the programs that
+created the graphics above.  And see the [API reference][7] for the
+nitty gritty.
+
+[1]: http://lambda.gsfc.nasa.gov/product/cobe/skymap_info_new.cfm
+[2]: http://fits.gsfc.nasa.gov/fits_wcs.html
+[3]: http://healpix.jpl.nasa.gov/
+[4]: http://lambda.gsfc.nasa.gov/product/cobe/skymap_info_new.cfm
+[5]: http://en.wikipedia.org/wiki/FITS
+[6]: http://www.dtic.mil/docs/citations/ADA010232
+[7]: http://rubydoc.info/github/crinc/QuadSphere/master/frames
+[8]: http://rubydoc.info/github/crinc/QuadSphere/master/QuadSphere/CSC.forward_distort
+[9]: https://raw.github.com/crinc/QuadSphere/master/examples/sphere.png
+[10]: https://raw.github.com/crinc/QuadSphere/master/examples/grid.png
+[11]: http://rubydoc.info/github/crinc/QuadSphere/master/QuadSphere

data/examples/binning.rb

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+# The example from the README.
+
+require 'quad_sphere/csc'
+
+def geographic_to_storage_bin(latitude, longitude)
+  # Convert both angles to radians.
+  latitude = latitude*Math::PI/180
+  longitude = longitude*Math::PI/180
+
+  # Geographic latitudes are normally geodetic; we convert this to
+  # geocentric because we want spherical coordinates.  The magic
+  # number below is the Earth's eccentricity, squared, using the WGS84
+  # ellipsoid.
+  latitude = Math.atan((1 - 6.69437999014e-3) * Math.tan(latitude))
+
+  # Apply the forward transformation...
+  face, x, y = QuadSphere::CSC.forward(longitude, latitude)
+
+  # ... then adjust x and y so they become integer coordinates on a
+  # 100x100 grid, with 0,0 being top-left, as used in pictures.
+  x = (100*(1+x)/2).floor
+  y = 99 - (100*(1+y)/2).floor
+
+  # And return the computed values.
+  [ face, x, y ]
+end
+
+[ [ 'Accra',          5.5500,   -0.2167 ],
+  [ 'Buenos Aires', -34.6036,  -58.3817 ],
+  [ 'Cairo',         30.0566,  -31.2262 ],
+  [ 'Honolulu',      21.3069, -157.8583 ],
+  [ 'Kuala Lumpur',   3.1597,  101.7000 ],
+  [ 'London',        51.5171,   -0.1062 ],
+  [ 'Longyearbyen',  78.216667, 15.55   ],
+  [ 'New Delhi',     28.6667,   77.2167 ],
+  [ 'New York',      40.7142,  -74.0064 ],
+  [ 'Quito',         -0.2186,  -78.5097 ],
+  [ 'Sydney',       -33.8683,  151.2086 ],
+  [ 'Ushuaia',      -54.8000,  -68.3000 ] ].each do |city, lat, lon|
+  face, x, y = geographic_to_storage_bin(lat, lon)
+  puts '%-12s - bitmap %d, x=%2d, y=%2d' % [city, face, x, y]
+end

data/examples/distort_closure.rb

@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+# Compute the closure error introduced by the curvilinear distortion
+# in QuadSphere::CSC.  This requires two additional gems: Joseph
+# Ruscio's Aggregate, and Willem van Bergen's ChunkyPNG.
+
+require 'quad_sphere/csc'
+require 'aggregate'
+require 'chunky_png'
+
+# Some routines to manipulate colours. We should really pack this
+# stuff in a gem one day...
+module Colour
+
+  # We expect an array of stops.  A gradient stop is an array of 4
+  # elements: a min value, a max value, a start colour, and an end
+  # colour.
+  #
+  # We expect the min of a stop to be always less than the max, and
+  # we expect all stops to have a max equal or smaller than the min
+  # of the next stop.  We expect all colours to be arrays of three
+  # floats.
+  #
+  # We don't validate any of this; just expect breakage if you don't
+  # conform.
+  def self.gradient_map(stops, value, rgbout)
+    stops.each do |min, max, start, finish|
+      if value >= min && value <= max
+        t = (value - min) / (max - min)
+        lerp(t, start, finish, rgbout)
+        return true
+      end
+    end
+
+    # If we're here, v is out of range.  We'll just hardcode a
+    # value.
+    rgbout[0] = 1.0
+    rgbout[1] = 0.0
+    rgbout[2] = 0.0
+    false
+  end
+
+  # Performs a linear interpolation between two colours.
+  def self.lerp(t, rgb1, rgb2, rgbout)
+    rgbout[0] = rgb1[0] + t*(rgb2[0] - rgb1[0])
+    rgbout[1] = rgb1[1] + t*(rgb2[1] - rgb1[1])
+    rgbout[2] = rgb1[2] + t*(rgb2[2] - rgb1[2])
+  end
+
+  # Converts as expected by chunkypng
+  def self.rgb1_to_i(rgb)
+    r = (rgb[0]*256).floor
+    g = (rgb[1]*256).floor
+    b = (rgb[2]*256).floor
+
+    (r < 0 ? 0 : r > 255 ? 255 : r) << 24 |
+      (g < 0 ? 0 : g > 255 ? 255 : g) << 16 |
+        (b < 0 ? 0 : b > 255 ? 255 : b) << 8 | 0xff
+  end
+end # module Colour
+
+# Size of the pretty pic. Computation time depends on the square of
+# this, so keep it reasonable.
+grid = 200
+
+image = ChunkyPNG::Image.new(grid,grid)
+stats = Aggregate.new
+
+# The expected maximum error is just below 2.4e-4, so we'll set a B&W
+# gradient white to that.
+stops = [ [ 0.0, 2.4e-4, [0.0,0.0,0.0], [1.0,1.0,1.0] ] ]
+rgb = Array.new(3)
+
+# We're mapping the range -1.0 to 1.0, inclusive, to 0 to grid-1.
+# Which is to say, if grid is 100, we want -1.0 at grid 0, and 1.0 at
+# grid 1...
+d = 2.0/(grid-1)
+
+# Perform grid² transformations of χ,ψ to x,y and back to χ',ψ', and
+# measuring the closure error.
+grid.times do |row|
+  grid.times do |col|
+    chi = col*d - 1.0
+    psi = row*d - 1.0
+    x = QuadSphere::CSC.forward_distort(chi,psi)
+    y = QuadSphere::CSC.forward_distort(psi,chi)
+    chi1 = QuadSphere::CSC.inverse_distort(x,y)
+    psi1 = QuadSphere::CSC.inverse_distort(y,x)
+    error = Math::sqrt((chi1-chi)**2 + (psi1-psi)**2)
+
+    # since we're dealing with very small errors, and Aggregate only
+    # works with integers, we scale the error for it.
+    stats << error*1e8
+
+    Colour.gradient_map(stops, error, rgb)
+    image[col,row] = Colour.rgb1_to_i(rgb)
+  end
+end
+
+# Print statistics:
+puts("samples: %d mean: %8g min: %8g max: %8g std_dev: %8g" %
+     [ stats.count,
+       stats.mean/1e8, stats.min/1e8, stats.max/1e8, stats.std_dev/1e8 ])
+
+# Print histogram:
+puts stats.to_s
+
+# Write the pretty pic:
+image.save('distort-error.png')

data/examples/gl1.rb

@@ -0,0 +1,164 @@
+# A wireframe view of the CSC projection.  You need OpenGL for this.
+
+require 'quad_sphere/csc'
+require 'opengl'
+
+class CSCWireframeApp
+
+  WINDOW_SIZE = 480
+
+  # How many subdivisions of each cube face.  Can be raised for
+  # smoother shading, at the cost of model complexity.
+  FACE_SUBDIV = 20
+
+  def run
+    @ang1 = 0
+    @ang2 = 0
+    @ang3 = 0
+
+    glutInit
+    glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB | GLUT_DEPTH)
+    glutInitWindowSize(WINDOW_SIZE, WINDOW_SIZE) 
+    glutCreateWindow('CSC')
+
+    glEnable(GL_DEPTH_TEST)
+    glPolygonMode(GL_FRONT_AND_BACK, GL_LINE)
+    glClearColor(1, 1, 1, 0.0)
+    setup_model
+
+    glutDisplayFunc(method :display) 
+    glutReshapeFunc(method :reshape)
+    glutKeyboardFunc(method :keyboard)
+
+    # And run.
+    glutMainLoop()
+  end
+
+  private
+
+  def setup_model
+    glGenLists(1)
+    glNewList(1, GL_COMPILE)
+
+    # The cube faces, and the colour we want each:
+    faces = [ [ QuadSphere::TOP_FACE,    [ 0.9, 0.25,  0.25, 1.0 ] ],  # red
+              [ QuadSphere::FRONT_FACE,  [ 0.25, 0.25, 0.9,  1.0 ] ],  # blue
+              [ QuadSphere::EAST_FACE,   [ 0.25, 0.8,  0.25, 1.0 ] ],  # green
+              [ QuadSphere::BACK_FACE,   [ 0.8,  0.75, 0.15, 1.0 ] ],  # yellow
+              [ QuadSphere::WEST_FACE,   [ 0.25, 0.9,  0.9,  1.0 ] ],  #cyan
+              [ QuadSphere::BOTTOM_FACE, [ 0.9,  0.25, 0.9,  1.0 ] ] ] #magenta
+
+    faces.each do |face, colour|
+      glColor3fv(colour);
+      # Calculate all the vertices we'll use for this face...
+      vertices = grid(face, FACE_SUBDIV)
+      # ... and arrange them in triangle strips:
+      mesh2quads(FACE_SUBDIV, vertices)
+    end
+
+    glEndList
+  end
+
+  def reshape(w, h)
+    glViewport(0, 0,  w,  h) 
+    glMatrixMode(GL_PROJECTION)
+    glLoadIdentity()
+    gluPerspective(60.0,  w.to_f / h.to_f, 1.0, 20.0)
+    glMatrixMode(GL_MODELVIEW)
+    glLoadIdentity()
+    gluLookAt(2.2,0,0, 0,0,0, 0,0,1)
+  end
+
+  def display
+    # XXX - maybe it'd be more efficient to only clear the depth
+    # buffer if we moved the model or camera?
+    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
+
+    # Rotate and draw the model.
+    glPushMatrix()
+    glRotate(@ang1, 0, 0, 1)
+    glRotate(@ang2, 1, 0, 0)
+    glRotate(@ang3, 0, 1, 0)
+    glCallList(1)
+    glPopMatrix()
+
+    # Done.
+    glutSwapBuffers()
+  end
+
+  def keyboard(key, x, y)
+    case  (key)
+    when ?s
+      @ang1 = (@ang1 + 5) % 360
+      glutPostRedisplay()
+    when ?a
+      @ang1 = (@ang1 - 5) % 360
+      glutPostRedisplay()
+    when ?w
+      @ang2 = (@ang2 + 5) % 360
+      glutPostRedisplay()
+    when ?q
+      @ang2 = (@ang2 - 5) % 360
+      glutPostRedisplay()
+    when ?x
+      @ang3 = (@ang3 + 5) % 360
+      glutPostRedisplay()
+    when ?z
+      @ang3 = (@ang3 - 5) % 360
+      glutPostRedisplay()
+    when ?r
+      @ang1 = @ang2 = @ang3 = 0
+      glutPostRedisplay()
+    when ?\e, ?Q
+      exit(0)
+    end
+  end
+
+  # Create a NxN grid of points on a face of the cube.  Note that this
+  # will generate (N+1)*(N+1) points.
+  def grid(face, n)
+    dx = 2.0/n
+    dy = 2.0/n
+    a = Array.new
+    n += 1
+
+    n.times do |j|
+      y = -1.0 + j*dy
+      n.times do |i|
+        x = -1.0 + i*dx
+        lon, lat = QuadSphere::CSC.inverse(face, x, y)
+        sx = Math::cos(lat) * Math::cos(lon)
+        sy = Math::cos(lat) * Math::sin(lon)
+        sz = Math::sin(lat)
+        a << [sx,sy,sz]
+      end
+    end
+
+    a
+  end
+
+  # p grid(0, 3)
+  #
+  # Create quad strips to represent a NxN mesh.  The given array
+  # should then contain (N+1)**2 points, arranged as N+1 rows of N+1
+  # points.
+
+  def mesh2quads(n,a)
+    dx = 2.0/n
+    dy = 2.0/n
+    row = n+1
+
+    n.times do |j|
+      glBegin(GL_QUAD_STRIP)
+      rowi = j*row
+      row.times do |x|
+        glVertex3fv(a[rowi+x])
+        glVertex3fv(a[rowi+row+x])
+      end
+      glEnd
+    end
+  end
+
+end
+
+CSCWireframeApp.new.run