*THIS DOCUMENT IS DEPRECATED*


About the color package 
For questions, please ask <Konstantin Poelke> or write to
<konstantin.poelke@fu-berlin.de>





- Why taking separate schemes for every dimension? 

One could think of providing just one interface ColorScheme that is implemented
by a particular color that can handle all dimensions. For instance, a gradient
color scheme could provide methods for configuring a color gradient for planar
images (2d) as well as for geometries in 3d space. There are two
possibilities for realizing this functionality: say we have a polar gradient and
want to set the (relative) center, then we could use setCenter2d(x,y) or
setCenter3d(x,y,z), or instead of providing the same method for every dimension,
we could have some "generic" version setCenter(PdVector) or setCenter(int[])
that takes an array (or a class wrapping an array). The length of this array
has to match the dimension of the scheme which could be set using a method
setDimension(int). 
However, there might be configurations that are available in
three dimension but not in two, e.g. the gradient scheme in 3d is to have an
option for two linear gradients in two independent directions.
Internally this would lead to necessary checks whether the methods can be
applied to the dimension the scheme is initiated with. 
Additionally, a two-dimensional color scheme should not provide any methods that
apply to three dimensions or higher, but only methods that are of
two-dimensional nature. 
Finally, the implementation of the actual algorithm that computes the color
(getColorImpl) is most likely to differ, dependent on the dimension. So a
getColor-method for a three-dimensional point will in general not be the same
implementation as the getColor-method for a two-dimensional point, although
both methods might implement some color gradient.

This is the reason why the color scheme package provides interfaces for the
most commonly used dimensions 1d, 2d and 3d, which are specializations of a
general color scheme.

Any color schemes for 1d,2d or 3d should therefore implement the corresponding
interface rather than the most general interface.

Higher-dimensional schemes (for which I don't have any applications yet, but
which can be thought of for e.g. coloring high-dimensional data sets) have to
implement the general color scheme.


In order to safe time implementing generic methods that apply for say
two-dimensional schemes (for instance decorators for different argument types
that have some natural two-dimensional interpretation as complex numbers) the
actual implementating class should derive from the corresponding
AbstractColorScheme class.

This allows for an as-easy-as-possible approach since for writing a new color
scheme, one just has to implement the actual "getColorImpl()" algorithm that
computes the color for a point.


- Why do you use int as a return type for colors? 

You are right, this is not the recommended way of speaking about objects in an
object-oriented world. A color should be something I can treat as a color, that
is an object Color that wraps all internal representations and hides them. In
contrast, dealing with a native integer type means dealing with a concrete
representation that is very technical to deal with and thus violates the
most important paradigm of abstraction in object oriented programming. 

However, there are at least four good reasons that convinced me: 

1. Performance! And this difference is remarkable! Dealing with Colors as object
means (implicitly) dealing with memory allocations caused by the new-operation.
These allocations would occur in at least the blend methods and the
"getColorImpl()" implementations, that are invoked many times (depending on the
number of points you want to color). I have written several tests which compare
two different blend methods, one using color objects, the other one using
low-level bit shifts and old C-era-stuff. Evaluating a color scheme that
consisted of 4 blended schemes on 1.000.000 pixels was about 15 times faster.

2. When writing an algorithm computing a color one actually computes the single
color values (e.g. in RGB or HSV space), but not a color object. So the actual
implementation of the "getColorImpl()" does not depend on a Color object. In
previous versions, the method ended with "return new Color(R,G,B)", now it ends
with "return rgbToInt(R,G,B)" which does not change anything in the computation
of R,G, or B.

3. My main usage is the generation of images that are colored using a color
scheme. These images are typically created using a BufferedImage object which
allocates a pixel buffer according to the image size, storing the colors for
every pixel. This pixel buffer is nothing else than an integer array, so the
colors are stored as int values. Of course one could use "Color.getRGB()" to
extract the integer representation of a color object. But as the natural data
type for dealing with colors is the native integer type, it is just natural to
use this type for the methods computing the colors as well.

4. If you still need a color object, just use "new Color(intValue)" ;)


- What is PuColorUtil? 

This class contains a bunch of methods I frequently made use of or that
appeared useful to have to me. This includes some methods I found in some
JavaView packages (dev.number) that I thought were a little bit misplaced
there.




