Color Table Generator PDD

Document Sample
Color Table Generator PDD Powered By Docstoc
					University of Southern Mississippi
Center of Higher Learning
High Performance Visualization Center
May 2002                                Report CHL-HPVC-02-20

Project Documentation Design (PDD)
HPVC Visualization Tool
Color Table Generator

                                                   D. R. Runnels
                                                    C. H. Johnson
                                                  Dr. P. H. Ranelli
                                                      M. Langford
                                            Center of Higher Learning
                      Project Documentation Design (PDD)
                            HPVC Visualization Tool
                             Color Table Generator

1.0 Introduction

   The High Performance Visualization Center, Center of Higher Learning has created various
   visualization tools with which HPVC programmers can easily provide different functionality
   in the visualization applications written. One such tool is the Color Table Generator.

   The Color Table Generator is a tool designed to create a color table based on various input
   parameters by the programmer. Once generated, a color table can be used to color objects
   with either smooth shade changes or abrupt changes in shade. In visualizing various
   scientific data, a consistent color can be assigned to a particular data value in the data set
   so that the value can be recognized by color as well as text.

1.1 Purpose of this document

   This document is a technical explanation of the HPVC Visualization Tool known as the
   Color Table Generator. It will provide all of the necessary information needed to
   understand the project architecture, individual components, interdependencies, and design
   decisions. A full explanation of how to use the package to include a menu, slider, or button
   into an application is given.

1.2 Scope of the development project

   The goal of this project is to provide a tool for creating a color table. The Color Table
   Generator not only creates a color table to be used in a programmer’s application it also
   provides an application that allows the programmer to view the color table with specific color
   index values displayed on colored tiles. This is useful to the programmer for determining
   the range of index values to be used in the visualization application.

   The programmer has the opportunity to choose the basic colors to be included in the table
   through command line prompts as well as the interval between colors derived from the
   same basic color. This project effectively provides the programmer with colors more
   numerous than the human eye can discern.

   Additionally, this project provides the programmer with a means for easily scaling a color to
   a particular data value. The programmer needs only send in applicable range values and
   the data set is scaled to the color table.

1.3 Definitions, acronyms, and abbreviations

   CAVE - A recursive acronym that stands for CAVE Automatic Virtual Environment,
         otherwise known as CAVE Audio Visual Environment.
   CHL - Center of Higher Learning
   HPVC – High Performance Visualization Center, a division of CHL

1.4 References

     M. Woo, J. Neider, T. Davis, “OpenGL programming guide, second edition.” Addison-
   Wesley Developers Press, Reading Massachusetts, 1997.
1.5 Overview of document

   The remainder of this document contains a description of the System Architecture, which
   will provide an overview of the various elements and components of the project. The
   system architecture description will also explain the interrelationships and dependencies
   among the components of the project, as well as the user interface.

   Section 3 provides a detailed Description of Components in a template format. The
   template is described in section 3.1. The advantages of code Reuse and Relationships
   are exploited and explained in section 4. This section details the role reuse plays in the
   project design as well as the motivation for any changes made in the design. Relationships
   to other products are also discussed. Section 5 explains the Design Decisions and
   Tradeoffs made due, for example, to system limitations. Finally, section 6 will explain how
   to Use this project, how to pre-process the data as well as how to compile and execute the

2.0 System Architecture Description

   This project is designed so that it will work on either the Linux or the SGI platforms. The
   outputs for the project are a header file containing the color table and an executable file that
   will display the color table generated.

2.1 Overview of modules / components

         Color Table Script – A script that compiles and runs the programs that will create
          and display the color table.

         Create Table – The program that actually creates and writes to a file the color table.

         Display Table – The program that displays the created color table.

2.2 Structure and relationships

   The following diagram, figure 1, will demonstrate the interrelationships among the above
   components. The programs have been written in C++ and are indicated in the diagram with
   a ‘.c’.
                                          Color Table Generator

                                                 User Interaction

                                              (header filename entered)
                Create Table                                                          Create Table

         maketable_linux.c                                                       maketable_sgi.c

                   includes:                                                                 includes:

                 fstream.h                                                              fstream.h
                  string.h                                                               string.h

       Input                                                                                             Input
                                                  Display Table


Color Table Script                                 stdlib.h                                       Color Table Script
color_table_linux                                  GL/glut.h                                      color_table_sgi

               Output                                                                               Output

                                          (header file containing color table)

                                       (executable file that displays color table)

                               Figure 1. Component Interrelationship Diagram
2.3 User interface

   The Color Table Generator has a command line interface with the programmer. Through
   the command line, the programmer enters the name for the header that will contain the color
   table and the range and number of colors to be included. Finally, when the color table has
   been generated it will automatically be displayed, see figure 2. The programmer can then
   use the keyboard to determine the index values of a chosen color or range of colors. As
   figure 3 shows the color table array index value is displayed as well as the red, green, and
   blue values. The RGB values are displayed to 6 decimal places.

 Figure 2. Example color table displayed.           Figure 3. Color table with index values

   When in the index display mode only a portion of the table is displayed so that the text can
   be seen. The programmer/user can then use the arrow keys to “scroll” through the table.

3.0 Detailed Description of Components

3.1 Component template description

Identification     The name of the component.
    Type           A module, subprogram, data file, etc.
  Purpose          Requirements implemented by the design component.
                   What the component does, the transformation process, the specific inputs
  Function         that are processed, the outputs that are produced, where the data items are
                   stored, and which data items are modified.
                   The internal structure of the component, the constituents of the component,
Subordinates       and the functional requirements satisfied by each part, functions within a
                   How the component’s function and performance relate to other components.
Dependencies       The other components that use this component. Interaction details such as
                   timing, interaction conditions (such as order of execution and data sharing).
                   Detailed descriptions of all external and internal interfaces as well as of any
  Interfaces       mechanisms for communicating through messages, parameters, or common
                   data areas. All error messages and error codes should be identified.
                   A complete description of all resources (hardware or software) external to
                   the component but required for carrying out its functions.
                   The full description of the functions presented in the Subordinates
 Processing        subsection. Pseudocode may be used to document algorithms, equations,
                   and logic.

3.2 Color Table Script

Identification     color_table_* ( * indicates sgi or linux depending on the platform used.)
    Type           Script
  Purpose          Simplify use of the color table generator tool.
                   This component compiles and runs the program that will generate the color
                   table. After the table has been created, this component will create and run a
                   program, dispColors.c that will display the color table for the
                   programmer. Finally, this script will delete the executable file that creates
                   the color table as well as various other files created in the process as a
                   clean up measure.
Subordinates       displaytable.c
                   This script requires that the displaytable.c and make_table_*.c
Dependencies       programs are in the same directory as the script and that all of the resources
                   necessary for these files are available to them.
                   The make_table_*.c program will create a temporary file that this script
  Interfaces       will concatenate to the displaytable.c file. The concatenation creates
                   the dispColors.c file, which is compiled and then deleted.
                   CC compiler to compile C++ on sgi and g++ compiler on linux. Additionally,
                   the following libraries will be necessary to compile the dispColors.c
                   program. On both sgi and linux necessary links include:
 Resources          -lglut –lGLU –lGL –lm –lglTexFont
                   On the sgi platform the following links are also necessary:
                   –lXext –lX11 –lXmu
                   make_table_*.c – compiled to create the maketable_* executable file
                   cat – concatenates the output from maketable_* to displaytable.c
                             and creates dispColors.c
 Processing        displayColors.c – compiled to create the dispColors executable file
                   rm – removes the maketable_* temporary output file, executable and
                             object files. The dispColors.c and object files are also

3.3 Create Table

Identification     maketable_*.c
    Type           Subprogram
  Purpose          Create the color table based on user input.
               This component receives user input to create a header file that contains
               the color table. This component also creates a temporary file that contains
  Function     the include statements (including the header filename) to be included into
               the displaytable.c program.
               void GenerateTable (ptr*, int, int)
               void GrayScale (ptr*)
Subordinates   void BasicColor (ptr, int, int)
               void InBetweenColor (ptr*, int, int, int, int)
               void printFunction ()
               This component is a stand-alone program that, to execute, depends simply
               on the correct compiler and user input, which is necessary for creating the
               output from this application.
Dependencies   The color_table_* script will expect a file named tempfile which is
               created by this component. This tempfile concatenates to
               displaytable.c to create dispColors.c, which provides the display
               of the color table.
               A command line interface allows the user to enter various parameter
               values used in the creation of the color table. This component then
               creates the color table and writes it to a file named by the user.
 Interfaces    Additionally, this component will create a temporary file that contains the
               include statement with the name entered by the user for the color table
               header file.
 Resources     C++ compiler. Necessary include files are: fstream.h and string.h
               GenerateTable – Calls the below functions to determines the red,
                       green, and blue values to be stored in the color table. This
                       function loops through the various basic colors chosen by the
               GrayScale – Determines the red, green, and blue values that will result in
                       a gradient of gray.
               BasicColor – Determines the red, green, and blue values to be stored in
                       the color table. These values create a gradient from black to
                       white based on the basic color sent as a parameter from the
                       GenerateTable function.
               InBetweenColor – Calculates the interval between basic color values as
                       well as between black and white based on user input. Using
                       this interval as the increment between colors this function
                       determines the red, green, and blue values that will create a
                       gradient between black and white, as well as a gradient
                       between the basic colors passed in as a parameter.
               PrintFunction – Writes to the header file the scaling function that will
                       accompany the color table.
3.4 Display Table

Identification   dispColors.c
    Type         Subprogram
                 For use by programmers to have a visual reference of the color that will
   Purpose       result from using an index or range of index values in the visualization
  Function       Display the color table created with the Color Table Generator.
                 init ()
                 display ()
Subordinates     arrows (int, int, int)
                 keyboard (unsigned char, int, int)
                 The dispColors.c program is created by the color_table_* script by
                 concatenating the displaytable.c program with the tempfile created
                 by the maketable_* executable program. Once created, the
                 dispColors.c program requires that the header file containing the color
                 table be in the current directory.
                 NOTE: The color_table_* script deletes both the dispColors.c and
                 dispColors.o files once the program has been compiled. Thus leaving
                 only the executable. Likewise, the tempfile that contains the include
                 statements are deleted. However, the script does not delete the
                 displaytable.c file from which the dispColors.c file derives.
                 Upon execution, the user can use keyboard input to scroll through the
  Interfaces     table and see the red, green, blue, and index values for each color.
                 C++ compiler and OpenGL graphics library. Necessary include files are:
                 GL/glut.h, fstream.h, colorTableFILENAME.h, stdlib.h, and glTexFont.h. In
                 addition, for the OpenGL libraries it is necessary to make the following
 Resources       links. On both the sgi and linux platforms link:
                 -lglut –lGLU –lGL –lm –lglTexFont
                 On the sgi platform also link:
                 –lXext –lX11 –lXmu
                 init – Sets up the Projection and Modelview modes to be used.
                 display – Displays the color table. Based on user keyboard input this
                           display may or may not contain textual indication of the red,
                           green, blue, and index values associated with each color
                 arrows – Receives user input and sets appropriate flags based on the
 Processing                user input to allow the displayed color table to be shifted up,
                           down, left or right.
                 keyboard – Receives user input and sets appropriate flags based
                         on this input to allow the displayed color table to zoom in,
                         zoom out, return to the default screen, or toggle text on or
4.0 Reuse and Relationships to Other Products

   This project uses the graphics library, OpenGL as well as the standard C++ libraries. It is
   designed for use with various other HPVC projects. The color tables generated can be used
   for several applications in which the colors available from the table are applicable, that is the
   table itself can be reused innumerable times.

   Likewise, the scaling function written into the color table header file can be used by any of
   the applications that include this file. This scaling function has the ability to calculate a scale
   for many applications in which one value must be mapped to another and is not limited to a
   color table application.

   The color table generator can be used to create everything from a very small color table to a
   very large color table. This flexibility provides a solution when space limitations become an

5.0 Design Decisions and Tradeoffs

   The goal of the project is to provide a visualization tool usable by HPVC programmers so
   that various visualization applications can easily include a color table customized for that
   application. HPVC programmers utilize both sgi and linux platforms to create their
   applications. Although most of the C++ and OpenGL commands are the same, a few
   differences between these platforms requires that the color table display application,
   dispColors.c be compiled differently on each different platform. The main difference is in
   the libraries to be linked at compile time. Similarly, the preferred C++ compiler is different
   on the different platforms. The HPVC machines have been set up so that the CC compiler
   is the most convenient to be used on any of the sgi machines, while linux machines contain
   the g++ compiler. These differences are addressed by having a different script for each
   platform. Although a different maketable.c program is not strictly necessary for each of
   the different platforms, they are included for the sake of simplicity.

   The decision to have two modes for displaying the color table solves the problem of screen
   space and legibility. The screen is often not large enough to display all of the colors in the
   color table as well as the rgb and index values in a legible manner. Therefore, it is designed
   such that the user can see all of the colors in the table displayed in tiles, or a portion of the
   color table such that the text is written over each color. The color tiles are larger in this
   second mode.

6.0 Use
   This project is designed for simplicity. The user merely has to have all of the Color Table
   Generator components in a directory. From the command line of this directory run the
   script. For example, on an sgi platform the command to run the Generator would be:
   After issuing the above command to run the Color Table Generator, answer the following
   questions. A color table should be created and displayed. The following keyboard
   commands will allow navigation through the color table display.

              Right Arrow – displays the colors to the right of the present location (if applicable)

              Left Arrow – displays the colors to the left of the present location (if applicable)

              Down Arrow – displays the colors below the present location (if applicable)
           Up Arrow – displays the colors above the present location (if applicable)

    +     Plus Symbol – causes the display to be zoomed in

    -     Minus Symbol – causes the display to be zoomed out

   r or R – Return to the default screen

   i or I – Toggle text on and off

NOTE: Although several shades of each color in the color table provides a smooth transition
      and a very aesthetic result, if the color table is very large, the display will be rather
      slow. It is best to limit the number of colors in the color table to that which will be
      utilized in the visualization application.

Shared By: