Simple tool for visualizing the output of random number generators (RNGs).
C
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
COPYING
ChangeLog
Makefile
README
spectra.c

README

================================================================================
=                  Spectra - Random Number Visualization Tool                  =
=                       Tom Nardi (MS3FGX@gmail.com)                           =
================================================================================

Spectra is a simple tool designed to aid in evaluating the quality of random
numbers generated by TRNGs and PRNGs. It does this by counting the occurrences
of characters within a given input file to help detect perceived bias, and then
visualizes the data as colored (or black and white) pixels in an image file to
aid in detection of repeating patterns.

As the human mind is exceptionally good at picking up on patterns that might
otherwise be difficult to detect mathematically, Spectra allows the user to
rapidly make a determination on the repeatability of numbers generated from the
suspect RNG.

--------------------------------------------------------------------------------
- Requirements                                                                 -
--------------------------------------------------------------------------------

Spectra requires relatively recent versions of GD and libpng. Spectra does not
require X to run, though you will obviously want a graphical environment when
trying to examine large images.

--------------------------------------------------------------------------------
- Installation                                                                 -
--------------------------------------------------------------------------------

To compile Spectra, simply run the command "make" in this directory. If you get
any message about missing libraries, use your distribution's package manager to
install them. This will let you run Spectra from the current directory for a
quick test, but not install it to the system.

To actually install Spectra, use the command "make install". Since this will
install Spectra to the system directories, you will need to run this as root or
through sudo.

When and if you want to remove Spectra, you would use the command "make
uninstall". As with "install", this makes changes to the system directories and
will therefore require root permissions.

In addition, if you are upgrading from a previous version, there is also the
command "make upgrade". This will remove any older versions of Spectra, compile
the new version, and finally install it to the system. As you might have
guessed, this also requires root permissions.

--------------------------------------------------------------------------------
- Usage                                                                        -
--------------------------------------------------------------------------------

Spectra takes an ASCII input file consisting of digits between 0 and 9. Any
other character in the file will cause Spectra to abort. Currently, Spectra
only supports output to PNG files, as JPG compression is too lossy and other
file formats (like BMP) are prohibitively large.

As of the current version, Spectra supports the following options:

-i <filename>
    This is the input file to process. Spectra must have an input file, or else
it will fail immediately.

-x <pixels>
    The width of the final image, default is 640. While there is no minimum
size, the larger the better. Maximum size is currently limited to 3000 pixels.

-y <pixels>
    The height of the final image, default is 480. While there is no minimum
size, the larger the better. Maximum size is currently limited to 3000 pixels.

--------------------------------------------------------------------------------
- What am I looking for?                                                       -
--------------------------------------------------------------------------------

Once it has finished rendering the image, Spectra will give you a breakdown of
how many times each character appeared in the file. This will give you a good
idea of the data's bias. Too many of one number is not a good sign, the spread
should be as close to even as possible.

Looking at the actual image file itself will allow you to visually detect any
patterns in the generated data. For example, a file that contained alternating
0's and 1's would show equal occurrences (which would be good), but visually
would appear as a mesh or grid type design.

An image from a good data source (Random.org) and an image from a very bad
data source are included under the /examples directory that came with the
source. While most RNGs won't look nearly as bad as the example given here, it
should give you an idea as to what to look for. Basically, any repeating
pattern or obvious clustering of pixels is a bad sign.

--------------------------------------------------------------------------------
- Character Colors                                                             -
--------------------------------------------------------------------------------

Currently, Spectra uses a static color-to-character mapping for the rendered
image. The colors are as follows:

0 - Black
1 - White
2 - Red
3 - Orange
4 - Yellow
5 - Green
6 - Blue
7 - Aqua
8 - Pink
9 - Purple

--------------------------------------------------------------------------------
- Packaging                                                                    -
--------------------------------------------------------------------------------

Spectra's Makefile supports using environment variables to modify the
installation so it can be more easily built into a binary package for your
distribution. You can pass compiler options and the installation directory to
the Makefile like so:

$ make CFLAGS="-O2 -march=i486 -mtune=i686"
gcc -O2 -march=i486 -mtune=i686 -lgd -lpng -lm spectra.c -o spectra
$ mkdir ./pkg
$ make install DESTDIR=./pkg
mkdir -p ./pkg/usr/bin/
mkdir -p ./pkg/usr/share/doc/spectra-1.2/
cp spectra ./pkg/usr/bin/
cp -a ChangeLog COPYING README examples/ ./pkg/usr/share/doc/spectra-1.2/

This allows you to easily script the build process and create a package using
the package creation software for your distribution of choice.

If you are able to build packages for your distribution, please let me know and
we can work something out for hosting them on the site.

--------------------------------------------------------------------------------
- License                                                                      -
--------------------------------------------------------------------------------

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License version 2 as published by the Free
Software Foundation.

This program 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.

For details, see the file "COPYING" in the source directory.

--------------------------------------------------------------------------------
- More Info                                                                    -
--------------------------------------------------------------------------------

For more information and updates, please see www.digifail.com