org.geotools.image.io
Class PaletteFactory

java.lang.Object
  extended by org.geotools.image.io.PaletteFactory

public class PaletteFactory
extends java.lang.Object

A factory for index color models created from RGB values listed in files. The palette definition files are text files containing an arbitrary number of lines, each line containing RGB components ranging from 0 to 255 inclusive. An optional fourth column may be provided for alpha components. Empty lines and lines starting with the '#' character are ignored. Example:

 # RGB codes for SeaWiFs images
 # (chlorophylle-a concentration)

   033   000   096
   032   000   097
   031   000   099
   030   000   101
   029   000   102
   028   000   104
   026   000   106
   025   000   107
 etc...
 
The number of RGB codes doesn't have to match the target color map size. RGB codes will be automatically interpolated as needed.

Since:
2.1
Version:
$Id: PaletteFactory.java 30679 2008-06-13 10:19:41Z acuster $
Author:
Martin Desruisseaux (IRD)

Constructor Summary
protected PaletteFactory()
          Constructs a default palette factory using this object class for loading palette definition files.
  PaletteFactory(java.io.File directory, java.lang.String extension, java.nio.charset.Charset charset, java.util.Locale locale)
          Constructs a palette factory using loading palette definition files in a specific directory.
  PaletteFactory(PaletteFactory fallback, java.lang.Class<?> loader, java.io.File directory, java.lang.String extension, java.nio.charset.Charset charset, java.util.Locale locale)
          Constructs a palette factory using an optional class for loading palette definition files.
  PaletteFactory(PaletteFactory fallback, java.lang.ClassLoader loader, java.io.File directory, java.lang.String extension, java.nio.charset.Charset charset, java.util.Locale locale)
          Constructs a palette factory using an optional class loader for loading palette definition files.
 
Method Summary
 java.lang.String[] getAvailableNames()
          Returns the list of available palette names.
 java.awt.Color[] getColors(java.lang.String name)
          Loads colors from a definition file.
 Palette getContinuousPalette(java.lang.String name, float minimum, float maximum, int dataType, int numBands, int visibleBand)
          Creates a palette suitable for floating point values.
static PaletteFactory getDefault()
          Gets the default palette factory.
 Palette getPalette(java.lang.String name, int size)
          Returns the palette of the specified name and size.
 Palette getPalette(java.lang.String name, int lower, int upper, int size, int numBands, int visibleBand)
          Returns the palette of the specified name and size.
 Palette getPalettePadValueFirst(java.lang.String name, int size)
          Returns a palette with a pad value at index 0.
 Palette getPalettePadValueLast(java.lang.String name, int size)
          Returns a palette with pad value at the last index.
protected  java.io.InputStream getResourceAsStream(java.lang.String name)
          Returns an input stream for reading the specified resource.
 java.util.Locale getWarningLocale()
          Returns the locale set by the last invocation to setWarningLocale(java.util.Locale) in the current thread.
static void scanForPlugins(java.lang.ClassLoader loader)
          Lookups for additional palette factories on the classpath.
 void setWarningLocale(java.util.Locale warningLocale)
          Sets the locale to use for formatting warning or error messages.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PaletteFactory

protected PaletteFactory()
Constructs a default palette factory using this object class for loading palette definition files. The default directory is "colors" relative to the directory of the subclass extending this class. The character encoding is ISO-8859-1 and the locale is US.

This constructor is protected because is it merely a convenience for subclasses registering themself as a service in the META-INF/services/org.geotools.image.io.PaletteFactory file. Users should invoke getDefault() instead, which will returns a shared instance of this class together with any custom factories found on the class path.

Since:
2.5

PaletteFactory

public PaletteFactory(java.io.File directory,
                      java.lang.String extension,
                      java.nio.charset.Charset charset,
                      java.util.Locale locale)
Constructs a palette factory using loading palette definition files in a specific directory. No class loader is used for loading the files.

Parameters:
directory - The base directory for palette definition files relative to current directory, or null for ".".
extension - File name extension, or null if there is no extension to add to filename. If non-null, this extension will be automatically appended to filename. It should starts with the '.' character.
charset - The charset to use for parsing files, or null for the default.
locale - The locale to use for parsing files, or null for the default.
Since:
2.5

PaletteFactory

public PaletteFactory(PaletteFactory fallback,
                      java.lang.ClassLoader loader,
                      java.io.File directory,
                      java.lang.String extension,
                      java.nio.charset.Charset charset,
                      java.util.Locale locale)
Constructs a palette factory using an optional class loader for loading palette definition files.

Parameters:
fallback - An optional fallback factory, or null if there is none. The fallback factory will be queried if a palette was not found in the current factory.
loader - An optional class loader to use for loading the palette definition files. If null, loading will occurs from the system current working directory.
directory - The base directory for palette definition files. It may be a Java package if a loader were specified. If null, then "." is assumed.
extension - File name extension, or null if there is no extension to add to filename. If non-null, this extension will be automatically appended to filename. It should starts with the '.' character.
charset - The charset to use for parsing files, or null for the default.
locale - The locale to use for parsing files, or null for the default.

PaletteFactory

public PaletteFactory(PaletteFactory fallback,
                      java.lang.Class<?> loader,
                      java.io.File directory,
                      java.lang.String extension,
                      java.nio.charset.Charset charset,
                      java.util.Locale locale)
Constructs a palette factory using an optional class for loading palette definition files. Using a class instead of a class loader can avoid security issue on some platforms (some platforms do not allow to load resources from a ClassLoader because it can load from the root package).

Parameters:
fallback - An optional fallback factory, or null if there is none. The fallback factory will be queried if a palette was not found in the current factory.
loader - An optional class to use for loading the palette definition files. If null, loading will occurs from the system current working directory.
directory - The base directory for palette definition files. It may be a Java package if a loader were specified. If null, then "." is assumed.
extension - File name extension, or null if there is no extension to add to filename. If non-null, this extension will be automatically appended to filename. It should starts with the '.' character.
charset - The charset to use for parsing files, or null for the default.
locale - The locale to use for parsing files. or null for the default.
Since:
2.2
Method Detail

getDefault

public static PaletteFactory getDefault()
Gets the default palette factory. This method creates a default instance looking for org/geotools/image/io/colors/*.pal files where '*' is a palette name. Next, this method scan for plugins using the default class loader. The result is cached for subsequent calls to this getDefault() method.


scanForPlugins

public static void scanForPlugins(java.lang.ClassLoader loader)
Lookups for additional palette factories on the classpath. The palette factories shall be declared in META-INF/services/org.geotools.image.io.PaletteFactory files.

Palette factories found are added to the chain of default factories. The next time that a getDefault().getPalette(...) method will be invoked, the scanned factories will be tried first. If they can't create a given palette, then the Geotools default factory will be tried last.

It is usually not needed to invoke this method directly since it is invoked automatically by getDefault() when first needed. This method may be useful when a specific class loader need to be used, or when the classpath content changed.

Parameters:
loader - The class loader to use, or null for the default one.
Since:
2.4

setWarningLocale

public void setWarningLocale(java.util.Locale warningLocale)
Sets the locale to use for formatting warning or error messages. This is typically the image reader locale. This locale is informative only; there is no garantee that this locale will be really used.

This method sets the locale for the current thread only. It is safe to use this palette factory concurrently in many threads, each with their own locale.

Parameters:
warningLocale - The locale for warning or error messages, or null for the default locale
Since:
2.4

getWarningLocale

public java.util.Locale getWarningLocale()
Returns the locale set by the last invocation to setWarningLocale(java.util.Locale) in the current thread.

Since:
2.4

getResourceAsStream

protected java.io.InputStream getResourceAsStream(java.lang.String name)
Returns an input stream for reading the specified resource. The default implementation delegates to the Class or ClassLoader method of the same name, according the loader argument type given to the constructor. Subclasses may override this method if a more elaborated mechanism is wanted for fetching resources. This is sometime required in the context of applications using particular class loaders.

Parameters:
name - The name of the resource to load, constructed as directory + name + extension where directory and extension were specified to the constructor, while name was given to the getPalette(java.lang.String, int) method.
Returns:
The input stream, or null if the resources was not found.
Since:
2.3

getAvailableNames

public java.lang.String[] getAvailableNames()
Returns the list of available palette names. Any item in this list can be specified as argument to getPalette(java.lang.String, int).

Returns:
The list of available palette name, or null if this method is unable to fetch this information.

getColors

public java.awt.Color[] getColors(java.lang.String name)
                           throws java.io.IOException
Loads colors from a definition file. If no colors were found in the current palette factory and a fallback was specified at construction time, then the fallback will be queried.

Parameters:
name - The palette's name to load. This name doesn't need to contains a path or an extension. Path and extension are set according value specified at construction time.
Returns:
The set of colors, or null if the set was not found.
Throws:
java.io.IOException - if an error occurs during reading.
javax.imageio.IIOException - if an error occurs during parsing.

getPalette

public Palette getPalette(java.lang.String name,
                          int size)
Returns the palette of the specified name and size. The palette's name doesn't need to contains a directory path or an extension. Path and extension are set according values specified at construction time.

Parameters:
name - The palette's name to load.
size - The index color model size.
Returns:
The palette.
Since:
2.4

getPalettePadValueFirst

public Palette getPalettePadValueFirst(java.lang.String name,
                                       int size)
Returns a palette with a pad value at index 0.

Parameters:
name - The palette's name to load.
size - The index color model size.
Returns:
The palette.
Since:
2.4

getPalettePadValueLast

public Palette getPalettePadValueLast(java.lang.String name,
                                      int size)
Returns a palette with pad value at the last index.

Parameters:
name - The palette's name to load.
size - The index color model size.
Returns:
The palette.
Since:
2.4

getPalette

public Palette getPalette(java.lang.String name,
                          int lower,
                          int upper,
                          int size,
                          int numBands,
                          int visibleBand)
Returns the palette of the specified name and size. The RGB colors will be distributed in the range lower inclusive to upper exclusive. Remaining pixel values (if any) will be left to a black or transparent color by default.

The palette's name doesn't need to contains a directory path or an extension. Path and extension are set according values specified at construction time.

Parameters:
name - The palette's name to load.
lower - Index of the first valid element (inclusive) in the index color model to be created.
upper - Index of the last valid element (exclusive) in the index color model to be created.
size - The size of the index color model to be created. This is the value to be returned by IndexColorModel.getMapSize().
numBands - The number of bands (usually 1).
visibleBand - The band to use for color computations (usually 0).
Returns:
The palette.
Since:
2.4

getContinuousPalette

public Palette getContinuousPalette(java.lang.String name,
                                    float minimum,
                                    float maximum,
                                    int dataType,
                                    int numBands,
                                    int visibleBand)
Creates a palette suitable for floating point values.

Parameters:
name - The palette name.
minimum - The minimal sample value expected.
maximum - The maximal sample value expected.
dataType - The data type as a DataBuffer.TYPE_FLOAT or DataBuffer.TYPE_DOUBLE constant.
numBands - The number of bands (usually 1).
visibleBand - The band to use for color computations (usually 0).
Since:
2.4


Copyright © 1996-2010 Geotools. All Rights Reserved.