poincare

Photographic Tiling of the Poincare Disk

Instructions for Use

 

Bill Horne

July 29, 2009

1         Contents of this Distribution

·        readme.htm – this document

·        COPYING – the GNU General Publick License v3

·        bin

o       poincare.exe – win32 executable

o       FreeImage.dll – Free Image library

·        doc

o       poincare.pdf – a technical paper describing the mathematics of how the program works

·        example

o       rocket_orig.jpg – an original image

o       mask.txt – a parameter file to generate the fundamental region

o       render.txt – a parameter file to generate a photographic tiling of the poincare disk

·        src – the C++ source files

2         Compiling the Source Code (optional)

To compile the source code, you will need to download the FreeImage open source image manipulation library.  FreeImage is used for low-level pixel manipulation and for reading and writing images into standard image formats like JPG.  FreeImage can be found at http://freeimage.sourceforge.net/

 

I compiled this code using Microsoft Visual Studio 2008.  I did not include the Visual Studio project files, but pretty much all you have to do is add all of the sources and link to the FreeImage libraries correctly.

 

I spent a little bit of time trying to get this to compile with gcc under cygwin, but I could never get it to interoperate with the FreeImage DLL correctly.  I did not try to complie this on any *nix machines, macs, etc.  If anyone has success compiling this using some other framework or on another platform, please let me know.

3         Installing the Program

I have provided a Windows 32-bit executable in case you don’t want to compile the sources directly, and would rather just run the code.  It is located in the bin directory and is called poincare.exe.

 

If you do not already have FreeImage installed, you must be sure that the file FreeImage.dll, which is located in the bin directory, is in some directory in your path.  If you don’t know how to set your path, try copying the file into C:\Windows\system32

4         Usage

This is a command line program that takes a parameter file as an argument whose entries are described below.

 

On Windows, do the following steps

  1. Select Start->Run.
  2. Type ‘cmd’ and click OK.
  3. cd into the bin directory in which you downloaded this program (e.g. ‘cd c:\poincare\bin’)
  4. Execute the program with a parameter file as an argument (e.g. “poincare ..\example\mask.txt”)

 

The parameter file has a set of parameters that tells the program how to run.  You can find two example parameter files in the example directory.

 

In general, generating one of these images is a two step process.

 

First, you have to identify the “fundamental region” from an image which you want to base the output on.  The fundamental region is a triangular-shaped region (actually, it’s a hyperbolic triangle --- see the accompanying technical documentation for a complete mathematical description).  This is an iterative process that not particularly intuitive. You have to determine four key points (px, py, rx, and ry) in the parameter file.  Each time you set those parmeters you will generate an output file which shows the masked input image.  You will find that you will have to keep tweaking those parameters, until you get the mask just right.  I often do a dozen or more iterations before I get this step right.  (Ideally, a GUI here would help tremendously!)

 

Second, only once you have identified the fundamental region can you render the tiling of the poincare disk.  This step is straightforward, although you may want to do this with a small value for the supersampling rate, say 1, or decrease the size of the rendered image so the program runs quickly.  Then, once you are satisfied, increase the supersampling rate to, say 4, to get a final image, but will take much more CPU time to do.

 

As you can see in the examples, the parameter file has a series of lines that look like:

 

key=value

 

Any line that begins with a ‘#’ is a comment line.

 

Here is a description of each parameter that is found in the parameter file.

 

parameter

valid values

description

p

Any integer such that (p-2)(q-2)>4

the fundamental region will have one angle of size π/p.

q

Any integer such that (p-2)(q-2)>4

the fundamental region will have one angle of size π/q.

jpegQuality

any integer in the range 0 to 100

the quality of the jpeg output.  100 gives the best quality, but will result in large images.

infile

any valid filename

the source image

outfile

any valid filename

the output image

action

“render” or “mask”

set to mask to generate just the fundamental region, set to render to generate a tiling of the disk

px

double

the x-coordinate of the corner of the fundamental region of angle π/p

py

double

the y-coordinate of the corner of the fundamental region of angle π/p

rx

double

the x-coordinate of the corner of the fundamental region of angle π/2

ry

double

the y-coordinate of the corner of the fundamental region of angle π/2

maskColor

“white”, “black”, “red”, “green”, “blue”, “cyan”, “magentav, or “yellow”

when the mask option is chosen for action, this is the color of everything but the fundamental region in the output image.

renderedSize

any integer > 0

the size of the rendered image in pixels

borderSize

any integer >= 0

the size of the border around the rendered disk

supersamplingRate

any integer > 0

the supersampling rate, used to reduce artifacts due to sampling in the rendered image.  A larger value will make the image look better, but will take longer to render

perturbationFactor

double

unused, set to 0.0

outOfBoundsColor

“white”, “black”, “red”, “green”, “blue”, “cyan”, “magentav, or “yellow”

the color of the region outside of the disk

unreachableColor

“white”, “black”, “red”, “green”, “blue”, “cyan”, “magentav, or “yellow”

in the event that for a given point within the disk cannot be associated with a point within the fundamental region in maxIterations steps, that pixel is colored with this color.

nonSourceColor

“white”, “black”, “red”, “green”, “blue”, “cyan”, “magentav, or “yellow”

in the event that the fundamental region is bigger than the source image, this will be the color of pixels that do not corresponds to a source pixel

maxIterations

any integer > 0

the maximum number of iterations to get from a pixel in the disk to a point in the fundamental region

negate

“true” or “false”

this will negate every other tile in the image.

 

5         Licence

Poincare is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

 

Poincare is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

 

You should have received a copy of the GNU General Public License along with Poincare.  If not, see <http://www.gnu.org/licenses/>.