ColormapDefinition.h

Go to the documentation of this file.

//# ColormapDefinition.h: wrapper for colormap function or look-up table
//# Copyright (C) 1998,1999,2000,2001
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library 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.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#ifndef TRIALDISPLAY_COLORMAPDEFINITION_H
#define TRIALDISPLAY_COLORMAPDEFINITION_H

#include <map>
#include <casa/aips.h>
#include <casa/Arrays/Vector.h>
#include <casa/IO/AipsIO.h>
#include <tables/Tables/Table.h>

namespace casa { //# NAMESPACE CASA - BEGIN

// <summary>
// This class defines a wrapper for a color function or look-up table.
// </summary>

// <use visibility=local>

// <reviewed reviewer="" date="yyyy/mm/dd" test="" demos="">
// </reviewed>

// <etymology>
// "ColormapDefinition" is the thing one uses to define a colormap.
// </etymology>

// <synopsis>
// ColormapDefinition is a class whose principal purpose is, given an
// input value in the range <src>[0.0, 1.0]</src>, to return an RGB
// triplet corresponding to that position in the colormap.  It can
// read definitions from and write definitions to <linkto
// class="Table"> Tables </linkto> on disk, thereby providing a
// mechanism for using custom colormaps for display applications.
//

// It supplies one built-in colormap <src>Greyscale 1</src>, which will
// always be available. The other colormaps are stored in AIPS++
// tables. The standard colormaps ar in
// <src>/aips++/data/colormaps/default.tbl</src>. These can be
// deactivated by putting <src>display.colormaps.usedefault: no</src> in
// the <src>.aipsrc</src> file.
// It also supplies user defined colormaps. It looks for the complete
// path to the user table in <src>.aipsrc</src> under
// <src>display.colormaps.usertable:</src>.
//
// ColormapDefinition is used by the <linkto
// class="Colormap">Colormap</linkto> class to generate color values
// for the <linkto class="ColormapManager"> ColormapManager</linkto>.
// </synopsis>

// <example>
// A ColormapDefinition corresponding to the system "rainbow" Colormap
// can be obtained and used as follows:
// <srcblock>
// ColormapDefinition rainbowDefinition(String("rainbow"));
// Float red, green, blue;
// for (uInt i = 0; i <= 100; i++) {
//   rainbowDefinition.getValues((Float)i/100.0, red, green, blue);
//   // ... do something with red, green, blue ...
// }
// </srcblock>
// Or a new ColormapDefinition with a red ramp and green and blue fixed
// at 0.5 could be constructed and saved for later use as follows:
// <srcblock>
// Vector<Float> reds(40), greens(40), blues(40);
// greens = 0.5;
// blues = 0.5;
// for (uInt i = 0; i < 40; i++) {
//   reds(i) = (Float)i / 39.0;
// }
// ColormapDefinition simpleRamp("redRamp", reds, greens, blues);
// Vector<String> synonyms(2);
// synonyms(0) = "RedRamp";synonyms(1) = "redramp";
// simpleRamp.save("mytable.tbl,synonyms);
// </srcblock>
// </example>

// <motivation>
// Needed to separate out ColormapDefinition from Colormap to give the
// programmer a way to over-ride the definition without having to also
// over-ride the shape function.
// </motivation>

// <thrown>
// <li> AipsError: unrecognized map name
// <li> AipsError: incompatible colormap definition version
// </thrown>

// <todo asof="1998/12/14">
// <li> add checks for red/green/blue componenets to have same number
//      of elements
// </todo>

        class RegEx;
        class String;

        class ColormapDefinition {

        public:

                // Construct a single color (white) Colormap
                ColormapDefinition();

                // Construct the known Colormap <src>mapName</src>, first looking for
                // a saved Colormap having this name, then resorting to a built-in
                // Colormap, and if that doesn't exist, throw an error
                explicit ColormapDefinition(const String & mapName);

                // Construct a new Colormap, using the supplied name and component
                // vectors
                ColormapDefinition(const String & mapName,
                                   const Vector<Float> & reds,
                                   const Vector<Float> & greens,
                                   const Vector<Float> & blues);

                // Obtain the Colormap value for the "index" value <src>0 <= t <= 1</src>
                void getValue(const Float t, Float & red, Float & green, Float & blue) const;

                // Change the Colormap values with the provided component vectors
                void setValues(const Vector<Float> & reds,
                               const Vector<Float> & greens,
                               const Vector<Float> & blues);

                // Write this ColormapDefinition to the named Table in the named
                // directory (default values are obtained from the user's
                // <src>.aipsrc</src> file.  If <src>overwrite</src> is
                // <src>True</src>, then an existing map of the same name in the
                // Table will be over-written.  If the named Table does not exist,
                // it will be created.

                // The table format has to conform with following scheme.
                // It must have five columns:
                // <src>CMAP_NAME</src> a String
                // <src>RED</src> a Float array of dim n
                // <src>GREEN</src> a Float array of dim n
                // <src>BLUE</src> a Float array of dim n
                // <src>SYNONYMS</src> a String array of dim m
                Bool save(const String &fullPathName,
                          const Vector<String> &synonyms,
                          const Bool &overwrite = True) const;

                // Return the names of the built-in colormaps.  If <src>uniqueonly</src>
                // is True (default), only the names of the unique colormaps
                // are returned, otherwise all colormap names are returned.
                typedef std::map<String,bool> colormapnamemap;
                static colormapnamemap builtinColormapNames(Bool uniqueonly = True);

                // Load Colormap definitions for a specified colormap<src>name</src>
                Bool loadColormap(const String& name);
                Bool loadBuiltinColormap(const String& name);

                // Write a ColormapDefinition to an ostream in a simple text form.
                friend ostream & operator << (ostream & os,
                                              const ColormapDefinition& pcreh);

        private:

                // The name of this ColormapDefinition
                String itsName;

                // Utility function to look if a colormap name is in a Table
                Bool queryColormapTable(const Table& table, const String& name);

                // load ColormapDefinitions from default location
                // aips++/data/colormaps/default.tbl
                // and/or location specified in <src>display.colormaps.usertable</src>
                static void loadColormapTable();

                //The loaded colormaps (a replacement for the builtins)
                //<group>
                static String ourDefaultColormap;
                static Table ourDefaultColormapTable;
                static Table ourUserColormapTable;
                static String ourTableVersion;
                //</group>

                // The Color component vectors for this ColormapDefinition
                Vector<Float> itsReds;
                Vector<Float> itsGreens;
                Vector<Float> itsBlues;

        };


} //# NAMESPACE CASA - END

#endif