---

worldviews.c

Go to the documentation of this file.

#include "worldviews.h"
#include "stringutils.h"



/* Static defaults */
int    WorldViews::random_seed =123454321;  /* Arbitrary default */

string WorldViews::default_type     = "Input_Gaussian";
string WorldViews::default_angle    = "Random PI/2 PI/2";
string WorldViews::default_position = "Uncorrelate &uncorrelation 0 RN  Random RN/2 RN/2";
string WorldViews::default_scale    = "1.0";
string WorldViews::default_offset   = "0.0";
string WorldViews::default_xsigma   = "&xsigma";
string WorldViews::default_ysigma   = "&ysigma";
string WorldViews::default_phase    = "Random PI/2 PI";
string WorldViews::default_size_scale = "1.0";
string WorldViews::default_image_filename = "image.pgm";
string WorldViews::default_clone_name = "";
       
string WorldViews::default_command    = "for i=0 i<inputs_pereye i=i+1 exec ${input_default_subcommand}";
string WorldViews::default_subcommand = "input_define Obj$i";
string WorldViews::imagepath = "../images/ ../../images/ ../../../images/ /usr/local/lissom/images/";


int    WorldViews::distribution=Uninitialized;
double WorldViews::input_offset=0.0;
int    WorldViews::inputs_pereye=1;
double WorldViews::xsigma=7;
double WorldViews::ysigma=1.5;
int    WorldViews::current_eye=0;
double WorldViews::scale_input=1.0;

Tristate WorldViews::input_log=True;

int    WorldViews::input_accum_type=Retinal_Composite::Max;


double WorldViews::input_separation_max=Uninitialized;
Tristate WorldViews::input_separation_max_enforce=False;
double WorldViews::input_separation_min=Uninitialized;
Tristate WorldViews::input_separation_min_enforce=False;




void  WorldViews::register_params_and_commands( void )
{
  /*
    Ensure that this routine is only called once; 
    valid since all the parameters are constant or static
  */
  static bool been_called=false;
  if (been_called) return;
  been_called=true;

  blackboard.define_param(DECLARE_PARAM(PARAM_INT,"input_current_eye",true,&current_eye));
  params_define_doc("input_current_eye",
          "Read-only parameter which reports the eye in which an object is currently\n"
          "being drawn, cleared, etc., e.g. by input_draw.  This can be useful for\n"
          "writing equations which place inputs at different but regularly-spaced\n"
          "positions, angles, etc. in each eye.\n\n"
          
          "This value is available during the command input_define, but it is not\n"
          "currently useful there because all subsequent eyes link directly to the\n"
          "values in the first eye (with or without uncorrelation), and thus any\n"
          "value computed for a parameter in the higher eyes is ignored.  There may\n"
          "be some way to circumvent this limitation.");
  SETFN_DEFINE2(input_current_eye,read_only_param_setfn2);
 
  PARAM_NN(PARAM_USTRING,input_default_clone_name,&default_clone_name,
          "Name of default object to clone when none is specified.  The default is to\n"
          "clone the entire contents of the retina, which can be useful for\n"
          "input_present_object to show all objects in their reset state.  However,\n"
          "when using input_define without specifying the name of the object to clone,\n"
          "the name should ordinarily be specified via this parameter.");

  PARAM_NN(PARAM_USTRING,input_default_image_filename,&default_image_filename,
          "Default filename used by Input_PGM when none is specified explicitly\n"
          "in a call to input_define.");

  PARAM_NN(PARAM_USTRING,input_default_command,&default_command,
          "Default command used to construct retinal objects when none are created\n"
          "explicitly by a call to input_define.  Usually just executes the\n"
          "input_default_subcommand \"inputs_pereye\" times, but can be changed to\n"
          "do something else, e.g. by setting the distribution parameter.");

  PARAM_NN(PARAM_USTRING,input_default_subcommand,&default_subcommand,
          "Command used by the default input_default_command to create each input.\n"
          "Usually just executes \"input_define\", but can be changed to something\n"
          "more specific.");

  PARAM_NN(PARAM_USTRING,input_default_type,&default_type,
          "Default type of retinal object to construct.  Accepts any of the possibilities\n"
          "for the <objtype> parameter of input_define.");

  PARAM_NN(PARAM_USTRING,input_default_angle,&default_angle,
          "Default theta used to construct most retinal objects when none is\n"
          "specified explicitly in a call to input_define.  Usually a randomly\n"
          "chosen angle from the full range for a symmetric stimulus (0..PI)\n"
          "each presentation.");

  PARAM_A(blackboard,"center_width",0.0,,
          "Default value of center_width used to construct some retinal objects,\n"
          "when none is specified explicitly in a call to input_define.");

  PARAM_NN(PARAM_USTRING,input_default_position,&default_position,
          "Default x and y center used to construct most retinal objects when none is\n"
          "specified explicitly in a call to input_define.  Usually a randomly chosen\n"
          "location on the full retina [0,RN) each presentation (for a persistent\n"
          "object defined with input_define), defaulting to the center of the retina\n"
          "(for temporary objects created with input_draw.)\n\n");
          
  PARAM_NN(PARAM_USTRING,input_default_scale,&default_scale,
          "Default intensity scale used to construct most retinal objects when none is\n"
          "specified explicitly in a call to input_define.");

  PARAM_NN(PARAM_USTRING,input_default_offset,&default_offset,
          "Default intensity offset used to construct most retinal objects when none is\n"
          "specified explicitly in a call to input_define.");

  PARAM_NN(PARAM_USTRING,input_default_xsigma,&default_xsigma,
          "Default xsigma used to construct most retinal objects when none is\n"
          "specified explicitly in a call to input_define.  Defaults to be a\n"
          "pointer to the global value of xsigma, so it will change any time\n"
          "that parameter does.");

  PARAM_NN(PARAM_USTRING,input_default_ysigma,&default_ysigma,
          "Default ysigma used to construct most retinal objects when none is\n"
          "specified explicitly in a call to input_define.  Defaults to be a\n"
          "pointer to the global value of ysigma, so it will change any time\n"
          "that parameter does.");

  PARAM_NN(PARAM_USTRING,input_default_phase,&default_phase,
          "Default phase used to construct some retinal objects when none is\n"
          "specified explicitly in a call to input_define.");

  PARAM_NN(PARAM_USTRING,input_default_size_scale,&default_size_scale,
          "Default size_scale for input objects taking that parameter.");

  PARAM_II(PARAM_3BOOL, input_log,&input_log,False,True,
          "If true, saves some information about the inputs presented at each iteration\n"
          "to the log file so that e.g. the input distribution can be analyzed.");

  PARAM_N(PARAM_DOUBLE,scale_input,
          "Input scaling factor.  The input level can be scaled to prevent saturating\n"  
          "the network.  See also input_offset.");
  
  PARAM_LL(PARAM_INT,   input_seed,&random_seed,0,                  
          "Value to which to reset the random number generator in input_reset.");

  PARAM_LL(PARAM_DOUBLE,input_separation_max,&input_separation_max,0,
          "When input_separation_max_enforce is true, the maximum allowable\n"
          "distance between input centers.");
  params_define_default_expr("input_separation_max","3.0*rf_radius"); /* Empirical */

  PARAM_II(PARAM_3BOOL, input_separation_max_enforce,&input_separation_max_enforce,False,True,
          "Whether or not to ensure that input centers are separated by at most\n"
          "input_separation_max.");

  PARAM_LL(PARAM_DOUBLE,input_separation_min,&input_separation_min,0,
          "When input_separation_min_enforce is true, the minimum allowable\n"
          "distance between centers of multiple simultaneous input patterns.\n"
          "Useful for ensuring that multiple patterns do not overlap spatially,\n"
          "so that neurons will not develop preferences for a combination of\n"
          "stimuli.  Note that with the input generation algorithm currently used,\n"
          "if this parameter is set to a large value relative to the retina size,\n"
          "the likelihood of a pattern appearing near the center of the retina will\n"
          "decrease, which can adversely affect training.  For even larger values it\n"
          "may be impossible to generate a position for a second stimulus (e.g. if\n"
          "the value is larger than RN.)  Consequently, you should ensure that when\n"
          "this parameter is in use the resulting training distribution (recorded\n"
          "in the .log file) is still as you intended.\n");
  params_define_default_expr("input_separation_min","2.2*rf_radius"); /* Empirical */


  PARAM_II(PARAM_3BOOL, input_separation_min_enforce,&input_separation_min_enforce,False,True,
          "Whether or not to ensure that input centers are separated by at least\n"
          "input_separation_min.");

  PARAM_II(PARAM_INT,   distribution,&distribution,Uninitialized,70,
          "Ordinarily, input distributions are defined using input_define or are\n"
          "generated automatically based on the defaults, but this parameter allows\n"
          "simple selection of a few that have historically been common.  If there\n"
          "is any doubt about their meaning, just use input_define explicitly.\n\n"

          "Unless otherwise noted, all distribute positions randomly and correlate\n"
          "them between the eyes using the uncorrelation parameter, all\n"
          "distribute angles randomly in the range [0..PI] radians, and keep all\n"
          "other parameters constant.\n\n"


          " 0 Uniformly random noise ranging from input_offset to (input_offset+\n"
          "   scale_input) at every location on the retina.\n\n\n"


          "13 Circular Gaussian input.\n"
          "   (Typical distribution for ocular dominance maps.)\n\n\n"

          
          "14 Circular Gaussian input with randomly chosen sigma.\n\n\n"


          "20 Ellipsoidal Gaussian input.\n"
          "   (Default distribution; typical for orientation maps.)\n\n\n"


          "21 Ellipsoidal Gaussian input with random eccentricities.  The\n"
          "   mean xsigma and ysigma are kept the same as in distribution 20.\n\n\n"


          "22 Ellipsoidal Gaussian input, all parallel to each other.\n\n\n"


          "23 Same as 20 with input_separation_min_enforce=True.\n\n\n"

          
          "24 Same as 22 with input_separation_min=True.\n\n\n"


          "25 Same as 23 with input_separation_max_enforce=True also.\n\n\n"
          

          "26 Same as 24 with input_separation_max_enforce=True also.\n\n\n"
          

          "60 Same as 20 except that all inputs are fixed at the center of the\n"
          "   retina. (Typical distribution for tilt aftereffect tests.)");
  /* Note that no setfn should be installed here for the distribution
     parameter since one is already installed for it in the Eyes class. */

  PARAM_NN(PARAM_INT,   input_accum_type,&input_accum_type,
          "Accumulation type for the retina.  See Accum_Max, Accum_Min, Accum_Add, etc.\n"
          "Note that changes to this parameter will have no effect once the retina has\n"
          "been initialized.");

  PARAM_NN(PARAM_USTRING,imagepath,&imagepath,
          "Space-separated list of paths to search for images to read.  The current\n"
          "directory is always searched first.");
  
  PARAM_NN(PARAM_DOUBLE,input_offset,&input_offset,
          "Constant value to add to each retinal input pixel.  See also scale_input.");

  PARAM_LL(PARAM_INT,   inputs_pereye,&inputs_pereye,0,
           "Default number of input items to create per eye, if none are explicitly\n"
           "defined by input_define.  When changed after the network has been\n"
           "initialized, undefines all current inputs and regenerates a new set\n"
           "using input_default_command.");
  /* Note that no setfn should be installed here for the inputs_pereye
     parameter since one is already installed for it in the Eyes class. */


   PARAM_A(blackboard,"uncorrelation",0.0,.add_lower_bound(0.0).add_upper_bound(1.0),  
           "Amount of uncorrelation between the input to different eyes. A value of\n"
           "0.0 means that the inputs are entirely correlated, i.e. identical, while\n"
           "1.0 means that they are entirely uncorrelated.");
  
   PARAM_LL(PARAM_DOUBLE,xsigma,&xsigma,0,
           "Default X sigma of ellipsoidal input Gaussian or similar patterns.\n"
           "When changed after the network has been initialized, undefines all\n"
           "current inputs and regenerates a new set using input_default_command.");

   PARAM_LL(PARAM_DOUBLE,ysigma,&ysigma,0,
           "Default Y sigma  of ellipsoidal input Gaussian or similar patterns.\n"
           "When changed after the network has been initialized, undefines all\n"
           "current inputs and regenerates a new set using input_default_command.");

   CONST_I(Accum_Max,int(Retinal_Composite::Max),False,
           "Input_Composite objects using this accum_type determine\n"
           "their activities at a given retinal location by taking the\n"
           "maximum of their children's activities at this location.  This\n"
           "makes it easier to combine objects from overlapping pieces.");

   CONST_I(Accum_Min,int(Retinal_Composite::Min),False,
           "Input_Composite objects using this accum_type determine\n"
           "their activities at a given retinal location by taking the\n"
           "minimum of their children's activities at this location.  This\n"
           "makes it easier to combine objects which are on in the background\n"
           "and off in the foreground.");

   CONST_I(Accum_Add,int(Retinal_Composite::Add),False,
           "Input_Composite objects using this accum_type determine\n"
           "their activities at a given retinal location by adding their\n"
           "children's activities at this location.  This facilitates construction\n"
           "of objects using Boolean specifications, such as punching out holes from\n"
           "a larger object.");

   CONST_I(Accum_OneHot,int(Retinal_Composite::OneHot),False,
           "Input_Composite objects using this accum_type select\n"
           "only a single child each iteration, as chosen by the <hot-specifier>\n"
           "parameter to Input_Composite.\n\n"

           "This accumulation type is useful for selecting one object (randomly, or in\n"
           "order) from a set of predefined stimuli.\n\n"

           "The <hot-specifier> should be a ValueGenerator in the range [0,1.0];\n"
           "it is used to generate an index in the range [0,number_of_children-1].\n"
           "Values outside of that range are wrapped back inside using a modulo\n"
           "operator, so e.g. a continuously incrementing value will cycle through\n"
           "all elements in order.  The default <hot-specifier> results in a random\n"
           "order.");

   CONST_I(Accum_Replace,int(Retinal_Composite::Replace),False,
           "Input_Composite objects using this accum_type obtain each\n"
           "pixel value from a single object, rather than combining the pixel\n"
           "values like most accum_types do.  The order of object definition\n"
           "determines the precedence; the underlying object shows through in\n"
           "regions outside the upper object's bounding box and in transparent\n"
           "regions of the upper object.\n\n"

           "This accumulation type is useful for pasting a small image containing\n"
           "both light and dark elements over a background, such that the\n"
           "light and dark areas both replace the background underneath.\n\n"

           "PGM images do not support transparency directly.  However, as an\n"
           "extension, the simulator will treat pixels with a value of 1.0\n"
           "(255/255; the brightest white) to be transparent if the PPM file\n"
           "contains a comment line \"#Transparent: 255\".  This line can be\n"
           "added to the file in any text editor; currently only value 255 is\n"
           "supported.\n\n"
           
           "With this accum_type, the background activity level for images is forced\n"
           "to zero so that transparency works as expected.  As a consequence, if no\n"
           "non-image object covers the background, the background will be zero rather\n"
           "than the background level of the image.");


  CONST_S(Input_Composite,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<theta> [<cx> [<cy> [<size_scale> [<scale> [<offset> [<accum_type>] [<hot-specifier>]]]]]]]\n\n"
          
          "Container for other objects, allowing a group of them to be moved\n"
          "and rotated as a unit.  Only makes sense for input_define rather than\n"
          "input_draw, at present.  The <name> parameter supplied in the call may\n"
          "henceforth serve as the name of the parent for a newly-defined object;\n"
          "the position, angle, and size of the newly-defined child object become\n"
          "relative to that of the composite.\n\n"

          "Parameter <accum_type> may be one of the following (prefixed with Accum_):\n"
          "Max, Min, Add, OneHot, Replace.  See Accum_OneHot for a description of the\n"
          "<hot-specifier>, and see Input_Gaussian for descriptions of the other\n"
          "parameters.  Example:\n\n"
          
          "input_define Face     \"\"   Input_Composite \"Normal PI/2 PI/18\"\n"
          "input_define Mask     Face Input_Gaussian   0  0  0.0 7.00 5  1\n"
          "input_define LeftEye  Face Input_Gaussian   0 -1 +2.5 1.25 2 -1\n"
          "input_define RightEye Face Input_Gaussian   0 -1 -2.5 1.25 2 -1\n"
          "input_define Mouth    Face Input_Gaussian   0 +5  0.0 1.25 2 -1");
  
  CONST_S(Input_UniformRandomNoise,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<scale> [<offset>]]\n\n"

          "The activation of each receptor in the retina is chosen randomly from\n"
          "a uniform distribution in the range <offset> to <offset>+<scale>.");
  
  CONST_S(Input_Gaussian,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<theta> [<cx> [<cy> [<xsigma> [<ysigma> [<scale> [<offset>]]]]]]]\n\n"

          "Two-dimensional Gaussian-shaped input object, i.e. a blob, with the\n"
          "indicated parameters:\n\n"
          
          "theta         angle in radians, measured upwards from the left\n"
          "              horizontal axis (contrary to standard\n"
          "              mathematical usage, for historical reasons))\n"
          "              (Defaults to input_default_angle.)\n\n"
          
          "(cx,cy)       location on retina (or parent object) of center\n"
          "              relative to an origin at the lower left corner,\n"
          "              extending upwards in the Y direction and to the\n"
          "              right in the X direction.  Values are floating-\n"
          "              point, with receptor (i,j) encompassing an area\n"
          "              starting at an upper left corner (i,j) and ending\n"
          "              just before the lower right corner (i+1,j+1).\n"
          "              Thus to center an item directly over receptor\n"
          "              (i,j), place it at (i+0.5,j+0.5).\n"
          "              (Defaults to input_default_position.)\n\n"
          
          "xsigma        sigma of the Gaussian in the X direction.\n"
          "              (Defaults to input_default_xsigma.)\n\n"
          
          "ysigma        sigma of the Gaussian in the Y direction.\n"
          "              (Defaults to input_default_ysigma.)\n\n"
          
          "scale         intensity scale (Defaults to 1.0, full intensity.)\n\n"
          
          "offset        intensity offset (Defaults to 0.0, no offset.)\n\n\n"


          "Example:\n"
          "  input_define Spot1    \"\" Input_Gaussian  \"Random PI/2 PI/2\" RN/4 RN/4 xsigma/2 ysigma 1.0 0.0\n");

  CONST_S(Input_Rectangle,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<cx> [<cy> [<xsigma> [<ysigma> [<scale>] [<offset>]]]]]\n\n"
          
          "Axis-aligned rectangle centered at <cx>,<cy> with width 2*<xsigma>,\n"
          "height 2*<ysigma>, and brightness <scale>.\n\n"

          "Depending on where the center falls on the grid, the actual length\n"
          "(height or width) may be larger or smaller than the nominal length by one\n"
          "pixel.  To get e.g. an odd width (e.g. 3), you should specify a <cx> at the\n"
          "center of a pixel (e.g. 1.5); this will ensure that the center pixel\n"
          "plus equal numbers of pixels on either side are included.  To get an even\n"
          "width, you should specify a pixel boundary instead (e.g. 2.0) so that an\n"
          "equal number of pixels are included on each side.\n\n"

          "This object type can be useful for drawing a pattern pixel-by-pixel.  To e.g.\n"
          "specify that the pixel at (3,1) should have activation 0.7, use:\n"
          "  Input_Rectangle  3.5 1.5 0.5 0.5 scale=0.7");
  
  CONST_S(Input_CircularGaussian,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<cx> [<cy> [<xsigma> [<scale> [<offset>]]]]]\n\n"
          
          "Two-dimensional circular Gaussian with radial sigma <xsigma>,\n"
          "which defaults to be a pointer to the global xsigma.\n"
          "See Input_Gaussian for descriptions of the other parameters.");
  
  CONST_S(Input_SineGrating,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<theta> [<freq> [<phase> [<scale> [<offset>] [<cx> [<cy>]]]]]]\n\n"
          
          "Sinusoidal grating input object which covers the entire retina.  The\n"
          "frequency and phase of the sine wave are set by <freq> and <phase>,\n"
          "and the origin of the function is (<cx>,<cy>).  The <phase> and origin\n"
          "default to random values at each presentation, centered at PI/2 and the\n"
          "and the center of the retina, respectively.  The <frequency> has an\n"
          "arbitrary default.\n\n"

          "Using the default <phase>, the origin can be used to fix the retinal\n"
          "location of one bar, regardless of the frequency.\n\n"

          "The <freq> is specified in terms of retinal units.  Thus at a frequency\n"
          "of 1.0, one sine grating cycle will take 2*PI (~6.3) retinal units.  The\n"
          "phase is specified in terms of radians; values repeat every 2*PI radians.\n\n"
          
          "Note that (for the default offset) the sine grating is half-rectified\n"
          "since negative activations are ignored.  To get a full sine wave in the\n"
          "standard activity range 0.0-1.0, use an offset of 0.5 and a scale of 0.5.");

  CONST_S(Input_Gabor,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<theta> [<cx> [<cy> [<xsigma> [<ysigma> [<freq> [<phase> [<scale> [<offset>]]]]]]]]]\n\n"
          "Gabor-shaped input object, i.e. a sine grating masked by a Gaussian.\n"
          "See Input_Gaussian and Input_SineGrating for descriptions of the\n"
          "parameters.");
  
  CONST_S(Input_FuzzyDisc,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<theta> [<cx> [<cy> [<ysigma> [<center_width> [<scale> [<offset>]]]]]]]\n\n"
          
          "Circular disc of radius <center_width> with one-dimensional Gaussian\n"
          "falloff (sigma <ysigma>) as distance increases from the disc.\n"
          "(Full brightness is maintained for the entire <center_width>, after\n"
          "which the brightness decreases according to a Gaussian of sigma\n"
          "ysigma.)  The <center_width> defaults to zero and the <ysigma> defaults\n"
          "to be a pointer to the global ysigma; such values match the appearance of\n"
          "Input_CircularGaussian, but will be slightly less efficient to compute.");

  CONST_S(Input_FuzzyLine,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<theta> [<cx> [<cy> [<ysigma> [<center_width> [<scale> [<offset>]]]]]]]\n\n"
          
          "Infinite line of width <center_width> with one-dimensional Gaussian\n"
          "falloff (sigma <ysigma>) as distance increases from that point.\n"
          "(Full brightness is maintained for the entire <center_width>, after\n"
          "which the brightness decreases according to a Gaussian of sigma\n"
          "ysigma.)  The <center_width> defaults to zero and the <ysigma> defaults\n"
          "to be a pointer to the global ysigma.");

  CONST_S(Input_FuzzyRing,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<cx> [<cy> [<ysigma> [<center_width> [<radius> [<scale> [<offset>]]]]]]]\n\n"
          
          "Circular ring (torus) of the given <radius> whose brightness is\n"
          "maximal for a distance of <center_width> around the radius, then\n"
          "falls off according to a one-dimensional Gaussian of sigma\n"
          "<ysigma> as radial distance increases from that point.  The\n"
          "<center_width> defaults to zero and the <ysigma> defaults to\n"
          "be a pointer to the global ysigma.");

  CONST_S(Input_PGM,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<filename> [<theta> [<cx> [<cy> [<size_scale> [<autoscale> [<transparent> [<scale> [<offset>]]]]]]]]]\n\n"

          "Reads input from the specified PGM-format or PBM-format file.\n\n"

          "The size_scale changes the effective size of the image on the retina.\n"
          "One common use of a non-unitary size_scale is to work with images larger\n"
          "than the final desired size, oversampling them to avoid pixellation effects\n"
          "when doing rotations, etc.  E.g. double-size images can be used with a\n"
          "size_scale of 0.5 and a world_size_scale of 2.0, with the same results as\n"
          "single-sized images would have except that (with proper input convolution)\n"
          "aliasing should be reduced.  See the documentation for Input_Gaussian for\n"
          "information about the other parameters.\n\n"

          "The parameters default to the defaults of Input_Gaussian for images\n"
          "smaller than the retina in any dimension, i.e. any images that can\n"
          "be placed at an arbitrary location and angle.  All larger images default\n"
          "to being upright with no angle variation, and to vary in position only\n"
          "as much as is possible without ever showing a border.  This distinction\n"
          "reflects differences in the primary uses of image objects -- they can\n"
          "act as regular objects which happen to be defined in an image file, or as\n"
          "literal specification of the entire contents of the retina.  Unfortunately,\n"
          "these defaults are not useful if you specify a size_scale explicitly;\n"
          "they are calculated assuming size_scale==1.0.\n\n"

          "If autoscale is nonzero, then the gray levels in the image are scaled so that\n"
          "the peak is at full scale.  The scale parameter, if any, then applies to this\n"
          "auto-scaled value.\n\n"
          
          "If you have a set of images that you want to present as the entire contents\n"
          "of the retina, e.g. to play a movie recorded from video, you can define\n"
          "hooks to clear the input and read in the appropriate frame each time. For\n"
          "example, assume that you have 999 frames stored in PGM files named\n"
          "image_001.pgm, image_002.pgm, ..., image_999.pgm.  To present the\n"
          "appropriate file at each iteration, you could use these commands:\n\n"

          "  hook before_input 1-999 input_undefine\n"
          "  hook before_input 1-999 input_define Image '' Input_PGM 'image_${03iteration}.pgm' PI/2 RN/2 RN/2 1.0\n\n"

          "Here the Input_PGM parameters are used to force the images to appear upright\n"
          "in the center of the retina at the same size each time, which is appropriate\n"
          "for full-retina images.  The '03' ensures that all frames use 3 digits for the\n"
          "iteration number, even for low numbers, to match the filenames.\n\n"

          "Note that due to accumulation of tiny floating-point errors in calculations,\n"
          "the bitmap presented might not match the source bitmap in every pixel, even\n"
          "when the input is presented axis-aligned and at a size_scale of 1.0. Be sure\n"
          "to examine the actual input presented if such details matter.  The code for\n"
          "this input type could be extended with special cases for direct rendering\n"
          "to eliminate such errors if need be.");
  
  CONST_S(Input_Clone,False,
          "Input object (see command input_define) with parameters:\n"
          "  [<name_of_original>]\n\n"
          
          "Defines an object that is a clone of the object with the given name.\n"
          "Any ValueGenerators the object has are cloned too, such that the clone\n"
          "has the same value distribution but different actual values.  The original\n"
          "object name (i.e. the object to clone) defaults to the value of\n"
          "input_default_clone_name; see that parameter's documentation for more\n"
          "details.  Named ValueGenerator arguments appropriate for the cloned\n"
          "object may be passed in after the name of the original object; these\n"
          "will be applied after cloning to override the inherited settings.\n\n"
          
          "The semantics of this operation are extremely tricky, and in fact it is\n"
          "only partially implemented.  Specifically, in the case when num_eyes>1\n"
          "and uncorrelation!=0, a cloned object will differ from the original\n"
          "by not having any uncorrelation introduced.  This difference is for\n"
          "very technical reasons having to do with how a cloned object is\n"
          "constructed for eyes other than the first, which is to clone the\n"
          "existing object in the current eye and replace its ValueGenerator\n"
          "parameter links to point to the newly cloned object in the first eye.\n"
          "This consideration is important only for input_define; input_draw\n"
          "always uses the starting state of the objects and thus is not\n"
          "affected by uncorrelation.");
}



void WorldViews::generate_default_contents( void )
{
  /* Execute input_default_command relatively silently */ 
  const int oldverbosity = ipc_msg_level;
  const int newverbosity = IPC_SUMMARY;
  if (ipc_msg_level > newverbosity) ipc_msg_level=newverbosity;
  cmddefs_exec_str(default_command.c_str());
  if (ipc_msg_level==newverbosity)  ipc_msg_level=oldverbosity;
}



bool WorldViews::next(void)
{
  /* Update parameters for this presentation */
  if (input_log)
    ipc_log(IPC_ONE,"Iteration: %06d",iteration);
  
  for (iterator eye=contents.begin(); eye!=contents.end(); eye++) {
    if (!(*eye)->next()) {
      const string name = (*eye)->name();
      ipc_notify(IPC_ONE,IPC_CAUTION,
                 "Failed to generate valid position for object in %s at iteration %06d",
                 name.c_str(),iteration);
    }
    else if (input_log) {
      string str=(*eye)->stringrep();
      ipc_log(IPC_ONE,"  [%s]",str.c_str());
    }
  }
  ipc_log(IPC_ONE,"\n");
  return true;
}


void WorldViews::define(const string& regionname, const double height, const double width)
{
  /* If one already exists, just ensure that it is of the right size */
  Retinal_AnchoredManagedComposite* existing =
    dynamic_cast<Retinal_AnchoredManagedComposite*>(Generic::find_named<Retinal_Object>(contents,regionname));
  if (existing) {
    existing->resize(height,width);
    return;
  }

  /* Otherwise create a new one */
  Retinal_Object::VarMap  vars;
  vars.set("hot",(contents.empty()? new UR_VGen(0.5,0.5) :
                  new VGen(contents[0]->get_varptr("hot"))));
  vars.set("size_scale",new VGen(1.0));
  vars.set("scale",new VGen(&scale_input));
  vars.set("offset",new VGen(&input_offset));
  
  Retinal_AnchoredManagedComposite newobj
  (regionname,
   &input_separation_min_enforce,   &input_separation_min,
   &input_separation_max_enforce,   &input_separation_max,
   Retinal_Composite::AccumulationType(input_accum_type),
   vars, height, width);

  /* This dynamic_cast can be removed once the Cray compiler supports
     derived-class virtual function return types. */
  Generic::insert_named(contents,regionname,dynamic_cast<value_type>(newobj.clone()));
}



bool WorldViews::create_object(StringArgs args, const string& name,
                               WorldViews& reference_contents,
                               bool link_eyes) // Should be made const
{
  DistributedValueGeneratorFactory<Retinal_Object::Variable> vgf;
  RetinalObjectStringArgs::DefaultsMap defaults; 
  
  /* ValueGenerators */
  defaults["transparent"]      = "-1";
  defaults["autoscale"]        = "0";
  defaults["theta"]            = "${input_default_angle}";
  defaults["cx"]               = "${input_default_position}";
  defaults["cy"]               = "${input_default_position}";
  defaults["xsigma"]           = "${input_default_xsigma}";
  defaults["ysigma"]           = "${input_default_ysigma}";
  defaults["radius"]           = "BaseRN/4"; // Arbitrary
  defaults["scale"]            = "${input_default_scale}";
  defaults["offset"]           = "${input_default_offset}";
  defaults["hot"]              = "Random 0.5 0.5";
  defaults["size_scale"]       = "${input_default_size_scale}";
  defaults["phase"]            = "${input_default_phase}";
  defaults["freq"]             = "0.5"; // Defaults to size comparable to default Gaussian
  defaults["center_width"]     = "&center_width";
  /* Other parameters */
  defaults["clone_name"]       = "${input_default_clone_name}";
  defaults["image_filename"]   = "${input_default_image_filename}";
  defaults["image_paths"]      = "${imagepath}";
  defaults["type"]             = "${input_default_type}";
  defaults["accum_type"]       = "Accum_Add";

  RetinalObjectFactory rof;
  
  /* Adds the new object to the specified parent(s), if any are found */
  Retinal_Object* masterobj=0;  
  for (unsigned int e=0; e<contents.size(); e++) {
    WorldViews::set_current_eye(e);
    StringArgs arglist = args; // Reset for each loop iteration
    
    const string specified_parent  = arglist.next(string(""));
    /* Special case: usually the empty string is used directly to
       represent 'any parent', but sometimes multiple quoting levels
       can make it difficult to represent an empty string, so the
       synonym "All" is also accepted. */
    const string parent  = (specified_parent == "All" ? string() : specified_parent);
    Retinal_Composite* parentptr = dynamic_cast<Retinal_Composite*>(contents[e]->find(parent));

    if (parentptr) {
      /*
        Linking objects between eyes can get very messy.  Currently
        the first eye for which an object is defined is considered the
        master eye, to which others link or uncorrelate.  For simple
        objects, the relationships are usually straightforward.
        However, if an existing object is being cloned, one must clone
        the object in the current eye and then replace the links to
        point to the new clone in the master eye.  In such cases no
        Uncorrelation is introduced, since that would be too difficult
        to reconstruct.  Call with link_eyes=false to get more
        predictable behavior, but of course then each eye will be
        independent.
      */
      RetinalObjectStringArgs sa(arglist, vgf, defaults, (link_eyes ? masterobj : 0));
      Retinal_Composite* basecomposite = reference_contents.contents[(link_eyes && masterobj) ? e : 0];
      Retinal_Object* newobj = rof.create(name, sa, basecomposite, parentptr);
      if (newobj) {
        parentptr->add(newobj);
        
        /*
          The first object defined (i.e., the object in the first eye
          found) is called the master; the others are linked or
          correlated with that one (if at all)
        */
        if (!masterobj) masterobj = newobj;
      }
    }
  }

  if (masterobj==0) {
    ipc_notify(IPC_ONE,IPC_ERROR,"Could not define input object");
    return 1;
  }
  
  return 0;
}


void WorldViews::remove_object(const string& parent, const string& name)
{
  for (unsigned int e=0; e<contents.size(); e++) {
    set_current_eye(e);
    Retinal_Composite* parentptr =
      dynamic_cast<Retinal_Composite*>(contents[e]->find(PARSE_C(parent.c_str())));
    
    if (parentptr) parentptr->remove(PARSE_C(name.c_str()));
  }
}
  

void WorldViews::print_object(const string& parent, const string& name) const
{
  for (unsigned int e=0; e<contents.size(); e++) {
    set_current_eye(e);
    Retinal_Object* parentptr = contents[e]->find(PARSE_C(parent.c_str()));

    if (parentptr) {
      Retinal_Object* childptr = parentptr->find(PARSE_C(name.c_str()));
      if (childptr)
        ipc_notify(IPC_ONE,IPC_SUMMARY,childptr->stringrep().c_str());
    }
  }
}
  

cmdstat WorldViews::set_distribution(int dist, bool& changed)
{  
  /* Define objects */
  string cmdstr="for i=0 i<inputs_pereye i=i+1 input_define";
  switch (dist) {
  case 0:
    cmdstr+=" noise \"\" Input_UniformRandomNoise &scale_input &input_offset";
    break;
    
  case 13:
    cmdstr+=" \"\" \"\" Input_CircularGaussian";
    break;
    
  case 14:
    cmdstr+=" \"\" \"\" Input_CircularGaussian \""
      + string(WorldViews::default_position) + "\" \"" +  WorldViews::default_position
      + "\" \"Random (ysigma-xsigma)/2 (ysigma-xsigma)/2\"";
    break;
    
  case 20: case 23: case 25: case 61:
    cmdstr+="";
    break;
    
  case 21:
    /*
      Originally this was handled by:
      
      * The mean X and Y sigmas are kept the same as in previous; *
      * generates variance uniformly distributed in 0.2 to 2*(xsigma^2) *
      local_xsigma = 0.2 + 2.0 * xsigma * my_random();
      local_ysigma = 0.2 + 2.0 * ysigma * my_random();
      
      It's not clear if the same behavior will result as it has been
      redefined here:
    */
    cmdstr+=" \"\" \"\" Input_Gaussian \""
      + string(WorldViews::default_angle) + "\" \"" + WorldViews::default_position + "\" \"" +  WorldViews::default_position
      + "\" \"Random xsigma 2*xsigma*xsigma\" \"Random ysigma 2*ysigma*ysigma\"";
    break;
    
  case 22: case 24: case 26:
    cmddefs_exec_str("input_define_generator parallel_angle \"Random PI/2 PI/2\"");
    cmdstr+=" \"\" \"\" Input_Gaussian &parallel_angle";
    break;
      
  case 60: 
    cmdstr+=" \"\" \"\" Input_Gaussian \""
      + string(WorldViews::default_angle) + "\" RN/2 RN/2";
    break;
    
  case Uninitialized: /* No-op */
    return CMD_NO_ERROR;

  default:
    ipc_notify(IPC_ONE,IPC_ERROR,"Don't know anything about distribution %d",dist);
    return CMD_PARAMETER_ERROR;
  }
  WorldViews::default_command = cmdstr;
  WorldViews::distribution=dist;


  /* Set general parameters */
  WorldViews::input_separation_min_enforce = ((dist==23 || dist==24 || dist==25 || dist==26)? True : False);
  WorldViews::input_separation_max_enforce = (                        (dist==25 || dist==26)? True : False);

  /* Declare that any existing input would need to be regenerated */
  changed=true;
  
  return CMD_NO_ERROR;
}

---