NAME

RaDoSt.pm - Random-dot stereograms

AUTHOR

David M. Chess, radost@davidchess.com

SYNOPSIS

  use strict;
  use RaDoSt;
  srand();      # The module doesn't do any seeding itself


  # create a simple stereogram and save as a GIF
  open OUTH, ">rds1.gif";
  my $rds = new RaDoSt::Stereogram(\&callback);
  binmode OUTH;
  print OUTH $rds->gif();
  close OUTH;


  # create a larger black-and-white version
  open OUTH, ">rds2.gif";
  $rds->{width} = 600;     # These can also be set
  $rds->{height} = 500;    #   at new() time
  $rds->{colorcount} = 2;
  $rds->{colormap} = [ [0,0,0] , [255,255,255] ];
  $rds->{arows} = 0;       # No alignment strip
  binmode OUTH;
  print OUTH $rds->gif();
  close OUTH;


  # Sample callback routine
  sub callback {
    my ($x,$y) = @_;
    # progress report
    print "Row $x \n" if not $y;
    # a floating diamond
    return 7 if abs($x-200)+abs($y-200) < 100;
    # over an undulating plain
    return 3*(sin($x/20)+sin($y/30));
  }

HISTORY

  1999/09/29 - First release version, 1.00

Creating a new object

RaDoSt::Stereogram::new(\&callback)

returns a new stereogram object, of the default height and width, taking z-height information from the given callback routine. Default settings can be overridden by modifying the instance variables, as described below.

Defaults are: 

  Width: 400
  Height: 400
  Colors: 16
  Colormap: undef
  Crossing width: 75
  Alignment rows: 5

RaDoSt::Stereogram::new(\&callback,width,height)

returns a new stereogram object, as above, with the given callback routine, width, and height.

Instance variables

$obj->{callback}

holds a reference to the sub that will be called for each point on the map, to obtain the height off the page of the 3D image at that point. The callback is passed two integers representing the acrossness and downness of the desired point, and it should return an integer whose absolute value is no more than (and in fact considerably less than) the crossing width.

Note that the callback routine is not called on the last (crossing width) columns of a row (since those columns are not in the 3D section of the image), or on the first (alignment rows) rows of the image (since those are used for the alignment strip).

$obj->{width} $obj->{height}

The, like, width and height of the, like, image to be produced.

$obj->{colorcount}

The number of colors to be used in the image; the default is 16.

$obj->{colormap}

A reference to an array of {colorcount} RGB values. Each element of the array references a three-element array giving the R, G and B values to be used for that color; the values should be in the range 0-255. The default colormap is undef, in which case the object makes up a brand-new random color map each time rendering is done.

$obj->{band}

the crossing width of the stereogram to be rendered. This is how many pels over the viewer will have to cross (well, actually, uncross) the eyes. The larger the crossing width, the more potential eyestrain, but the wider the range of heights that can be used in the image. The default, 75, generally works fine, and there's usually no reason to fiddle with it. (If you make it too big, the result will be unviewable except by those few people who can actually point their eyes outward.)

$obj->{arows}

the number of rows at the top of the image to be used for the alignment strip (a mostly-solid strip with periodic tick-marks, to aid the viewer). The default is five; if this variable is set to zero, no alignment strip will be created.

Rendering

RaDoSt::Stereogram::gif()

returns, as a potentially rather long binary string, a GIF-format representation of a random-dot stereogram made with the properties currently assigned to the object. This method may be called multiple times, twiddling with instance variables in between, to generate multiple images from a single object.

This method is *not* speedy.