
                             The "examples" directory
                            ========================

Probably the most useful item in this directory is the command-line script

    genRand2D 

that can be called simply with two arguments for generating a set of random
points.  A call to this script looks like

    genRand2D --histfile  your_histogram_file.csv --bbfile  your_bounding_box_file.csv

where the `--histfile' option supplies the name of the file that contains the 2D
input histogram and the `--bbfile' option the name of the file that defines the
relevant bounding box in the XY-plane.  You can also execute the command line

    genRand2D  --help

for displaying information as to what is required by the two options for the
genRand2D command.  The command-line invocation of genRand2D gives you 2000
random points that are deposits in a file whose name is printed out in your
terminal window in which you execute the command.

To become more familiar with all of the different options you can use with this
module in order to control random point generation, you should experiment with
the script:

    generate_random_points.pl

You can feed it different 2D histograms --- even made-up 2D histograms --- and look
at the histogram of the generated random points to see how well the module is
working.  Keep in mind, though, if your made-up input histogram has disconnected
blobs in it, the random-points that are generated may correspond to just one of the
blobs.  Since the process of random-point generation involves a random walk, the
algorithm may not be able to hop from one blob to another in the input histogram if
they are too far apart.  As to what exactly you'll get by way of the output histogram
would depend on your choice of the width of the proposal density.

This directory contains the following histogram and bounding-box files for you
to get started:

    hist1.csv   bb1.csv

    hist2.csv   bb2.csv    

If you run the generate_random_points.pl script for the hist1.csv and bb1.csv
files, the histogram you get for the 2000 random point generated by the module
is likely to look like what you see in the file

    output_histogram_for_hist1.png 

On a Linux machine, you can see this histogram with the usual `display' command
from the ImageMagick library.  And if you run generate_random_points.pl script
for the hist2.csv and bb2.csv files, you'll see an output histogram that should
look like what you see in 

    output_histogram_for_hist2.png

You should also try making the command-line calls:

    enRand2D --histfile hist1.csv --bbfile bb1.csv

    enRand2D --histfile hist2.csv --bbfile bb2.csv


