001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: * (C) 2002, Centre for Computational Geography
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation;
010: * version 2.1 of the License.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * Contacts:
018: * UNITED KINGDOM: James Macgill. j.macgill@geog.leeds.ac.uk
019: */
020: package org.geotools.styling;
021:
022: import org.opengis.filter.expression.Expression;
023:
024: /**
025: * The RasterSymbolizer describes how to render raster/matrix-coverage data
026: * (e.g., satellite photos, DEMs).
027: *
028: * <p>
029: * The details of this object are taken from the <a
030: * href="https://portal.opengeospatial.org/files/?artifact_id=1188"> OGC
031: * Styled-Layer Descriptor Report (OGC 02-070) version 1.0.0.</a>:
032: * <pre><code>
033: * <xs:element name="RasterSymbolizer">
034: * <xs:complexType>
035: * <xs:sequence>
036: * <xs:element ref="sld:Geometry" minOccurs="0"/>
037: * <xs:element ref="sld:Opacity" minOccurs="0"/>
038: * <xs:element ref="sld:ChannelSelection" minOccurs="0"/>
039: * <xs:element ref="sld:OverlapBehavior" minOccurs="0"/>
040: * <xs:element ref="sld:ColorMap" minOccurs="0"/>
041: * <xs:element ref="sld:ContrastEnhancement" minOccurs="0"/>
042: * <xs:element ref="sld:ShadedRelief" minOccurs="0"/>
043: * <xs:element ref="sld:ImageOutline" minOccurs="0"/>
044: * </xs:sequence>
045: * </xs:complexType>
046: * </xs:element>
047: * </code></pre>
048: * The following example applies a coloring to elevation (DEM) data (quantities
049: * are in meters):
050: * <pre>
051: * <RasterSymbolizer>
052: * <Opacity>1.0</Opacity>
053: * <ColorMap>
054: * <ColorMapEntry color="#00ff00" quantity="-500"/>
055: * <ColorMapEntry color="#00fa00" quantity="-417"/>
056: * <ColorMapEntry color="#14f500" quantity="-333"/>
057: * <ColorMapEntry color="#28f502" quantity="-250"/>
058: * <ColorMapEntry color="#3cf505" quantity="-167"/>
059: * <ColorMapEntry color="#50f50a" quantity="-83"/>
060: * <ColorMapEntry color="#64f014" quantity="-1"/>
061: * <ColorMapEntry color="#7deb32" quantity="0"/>
062: * <ColorMapEntry color="#78c818" quantity="30"/>
063: * <ColorMapEntry color="#38840c" quantity="105"/>
064: * <ColorMapEntry color="#2c4b04" quantity="300"/>
065: * <ColorMapEntry color="#ffff00" quantity="400"/>
066: * <ColorMapEntry color="#dcdc00" quantity="700"/>
067: * <ColorMapEntry color="#b47800" quantity="1200"/>
068: * <ColorMapEntry color="#c85000" quantity="1400"/>
069: * <ColorMapEntry color="#be4100" quantity="1600"/>
070: * <ColorMapEntry color="#963000" quantity="2000"/>
071: * <ColorMapEntry color="#3c0200" quantity="3000"/>
072: * <ColorMapEntry color="#ffffff" quantity="5000"/>
073: * <ColorMapEntry color="#ffffff" quantity="13000"/>
074: * </ColorMap>
075: * <OverlapBehavior>
076: * <AVERAGE/>
077: * </OverlapBehavior>
078: * <ShadedRelief/>
079: * </RasterSymbolizer>
080: * </pre>
081: * Here is a rather artificial mutli-band raster symbol:
082: * <pre>
083: * <RasterSymbolizer>
084: * <Opacity>1.0</Opacity>
085: * <ColorMap>
086: * <ColorMapEntry color="#000000" quantity="0"/>
087: * <ColorMapEntry color="#ffffff" quantity="255"/>
088: * </ColorMap>
089: * <ChannelSelection>
090: * <RedChannel>
091: * <SourceChannelName>1</SourceChannelName>
092: * <ContrastEnhancement>
093: * <Histogram/>
094: * </ContrastEnhancement>
095: * </RedChannel>
096: * <GreenChannel>
097: * <SourceChannelName>2</SourceChannelName>
098: * <ContrastEnhancement>
099: * <GammaValue>2.5</GammaValue>
100: * </ContrastEnhancement>
101: * </GreenChannel>
102: * <BlueChannel>
103: * <SourceChannelName>3</SourceChannelName>
104: * <ContrastEnhancement>
105: * <Normalize/>
106: * </ContrastEnhancement>
107: * </BlueChannel>
108: * </ChannelSelection>
109: * <OverlapBehavior>
110: * <LATEST_ON_TOP/>
111: * </OverlapBehavior>
112: * <ContrastEnhancement>
113: * <GammaValue>1.0</GammaValue>
114: * </ContrastEnhancement>
115: * </RasterSymbolizer>
116: * </PRE>
117: * $Id: RasterSymbolizer.java 25459 2007-05-08 05:19:25Z jgarnett $
118: * </p>
119: *
120: * @author Ian Turton, CCG
121: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/styling/RasterSymbolizer.java $
122: */
123: public interface RasterSymbolizer extends Symbolizer {
124: /**
125: * The interpretation of Geometry is system-dependent, as raster data may
126: * be organized differently from feature data, though omitting this
127: * element selects the default raster-data source. Geometry-type
128: * transformations are also system-dependent and it is assumed that this
129: * capability will be little used.
130: *
131: * @param geometryPropertyName the name of the Geometry
132: */
133: void setGeometryPropertyName(String geometryPropertyName);
134:
135: /**
136: * The interpretation of Geometry is system-dependent, as raster data may
137: * be organized differently from feature data, though omitting this
138: * element selects the default raster-data source. Geometry-type
139: * transformations are also system-dependent and it is assumed that this
140: * capability will be little used.
141: *
142: * @return the name of the geometry
143: */
144: String getGeometryPropertyName();
145:
146: /**
147: * sets the opacity for the coverage, it has the usual meaning.
148: *
149: * @param opacity An expression which evaluates to the the opacity (0-1)
150: */
151: void setOpacity(Expression opacity);
152:
153: /**
154: * fetch the expresion which evaluates to the opacity fo rthis coverage
155: *
156: * @return The expression
157: */
158: Expression getOpacity();
159:
160: /**
161: * The ChannelSelection element specifies the false-color channel selection
162: * for a multi-spectral raster source (such as a multi-band
163: * satellite-imagery source). Either a channel may be selected to display
164: * in each of red, green, and blue, or a single channel may be selected to
165: * display in grayscale. (The spelling ?gray? is used since it seems to
166: * be more common on the Web than ?grey? by a ratio of about 3:1.)
167: * Contrast enhancement may be applied to each channel in isolation.
168: * Channels are identified by a system and data-dependent character
169: * identifier. Commonly, channels will be labelled as ?1?, ?2?, etc.
170: *
171: * @param channel the channel selected
172: */
173: void setChannelSelection(ChannelSelection channel);
174:
175: /**
176: * The ChannelSelection element specifies the false-color channel selection
177: * for a multi-spectral raster source (such as a multi-band
178: * satellite-imagery source). Either a channel may be selected to
179: * display in each of red, green, and blue, or a single channel may be
180: * selected to display in grayscale. (The spelling ?gray? is used since
181: * it seems to be more common on the Web than ?grey? by a ratio of about
182: * 3:1.) Contrast enhancement may be applied to each channel in isolation.
183: * Channels are identified by a system and data-dependent character
184: * identifier. Commonly, channels will be labelled as ?1?, ?2?, etc.
185: *
186: * @return the ChannelSelection object set or null if none is available.
187: */
188: ChannelSelection getChannelSelection();
189:
190: /**
191: * The OverlapBehavior element tells a system how to behave when multiple
192: * raster images in a layer overlap each other, for example with
193: * satellite-image scenes. LATEST_ON_TOP and EARLIEST_ON_TOP refer to the
194: * time the scene was captured. AVERAGE means to average multiple scenes
195: * together. This can produce blurry results if the source images are not
196: * perfectly aligned in their geo-referencing. RANDOM means to select an
197: * image (or piece thereof) randomly and place it on top. This can
198: * produce crisper results than AVERAGE potentially more efficiently than
199: * LATEST_ON_TOP or EARLIEST_ON_TOP. The default behaviour is
200: * system-dependent.
201: *
202: * @param overlap the expression which evaluates to LATEST_ON_TOP,
203: * EARLIEST_ON_TOP, AVERAGE or RANDOM
204: */
205: void setOverlap(Expression overlap);
206:
207: /**
208: * The OverlapBehavior element tells a system how to behave when multiple
209: * raster images in a layer overlap each other, for example with
210: * satellite-image scenes. LATEST_ON_TOP and EARLIEST_ON_TOP refer to the
211: * time the scene was captured. AVERAGE means to average multiple scenes
212: * together. This can produce blurry results if the source images are
213: * not perfectly aligned in their geo-referencing. RANDOM means to select
214: * an image (or piece thereof) randomly and place it on top. This can
215: * produce crisper results than AVERAGE potentially more efficiently than
216: * LATEST_ON_TOP or EARLIEST_ON_TOP. The default behaviour is
217: * system-dependent.
218: *
219: * @return The expression which evaluates to LATEST_ON_TOP,
220: * EARLIEST_ON_TOP, AVERAGE or RANDOM
221: */
222: Expression getOverlap();
223:
224: /**
225: * The ColorMap element defines either the colors of a palette-type raster
226: * source or the mapping of fixed-numeric pixel values to colors. For
227: * example, a DEM raster giving elevations in meters above sea level can
228: * be translated to a colored image with a ColorMap. The quantity
229: * attributes of a color-map are used for translating between numeric
230: * matrixes and color rasters and the ColorMap entries should be in order
231: * of increasing numeric quantity so that intermediate numeric values can
232: * be matched to a color (or be interpolated between two colors). Labels
233: * may be used for legends or may be used in the future to match character
234: * values. Not all systems can support opacity in colormaps. The default
235: * opacity is 1.0 (fully opaque). Defaults for quantity and label are
236: * system-dependent.
237: *
238: * @param colorMap the ColorMap for the raster
239: */
240: void setColorMap(ColorMap colorMap);
241:
242: /**
243: * The ColorMap element defines either the colors of a palette-type raster
244: * source or the mapping of fixed-numeric pixel values to colors. For
245: * example, a DEM raster giving elevations in meters above sea level can
246: * be translated to a colored image with a ColorMap. The quantity
247: * attributes of a color-map are used for translating between numeric
248: * matrixes and color rasters and the ColorMap entries should be in order
249: * of increasing numeric quantity so that intermediate numeric values can
250: * be matched to a color (or be interpolated between two colors). Labels
251: * may be used for legends or may be used in the future to match character
252: * values. Not all systems can support opacity in colormaps. The
253: * default opacity is 1.0 (fully opaque). Defaults for quantity and
254: * label are system-dependent.
255: *
256: * @return the ColorMap for the raster
257: */
258: ColorMap getColorMap();
259:
260: /**
261: * The ContrastEnhancement element defines contrast enhancement for a
262: * channel of a false-color image or for a color image. In the case of a
263: * color image, the relative grayscale brightness of a pixel color is
264: * used. ?Normalize? means to stretch the contrast so that the dimmest
265: * color is stretched to black and the brightest color is stretched to
266: * white, with all colors in between stretched out linearly. ?Histogram?
267: * means to stretch the contrast based on a histogram of how many colors
268: * are at each brightness level on input, with the goal of producing equal
269: * number of pixels in the image at each brightness level on output. This
270: * has the effect of revealing many subtle ground features. A ?GammaValue?
271: * tells how much to brighten (value greater than 1.0) or dim (value less
272: * than 1.0) an image. The default GammaValue is 1.0 (no change). If none
273: * of Normalize, Histogram, or GammaValue are selected in a
274: * ContrastEnhancement, then no enhancement is performed.
275: *
276: * @param ce the contrastEnhancement
277: */
278: void setContrastEnhancement(ContrastEnhancement ce);
279:
280: /**
281: * The ContrastEnhancement element defines contrast enhancement for a
282: * channel of a false-color image or for a color image. In the case of a
283: * color image, the relative grayscale brightness of a pixel color is
284: * used. ?Normalize? means to stretch the contrast so that the dimmest
285: * color is stretched to black and the brightest color is stretched to
286: * white, with all colors in between stretched out linearly. ?Histogram?
287: * means to stretch the contrast based on a histogram of how many colors
288: * are at each brightness level on input, with the goal of producing
289: * equal number of pixels in the image at each brightness level on output.
290: * This has the effect of revealing many subtle ground features. A
291: * ?GammaValue? tells how much to brighten (value greater than 1.0) or dim
292: * (value less than 1.0) an image. The default GammaValue is 1.0 (no
293: * change). If none of Normalize, Histogram, or GammaValue are selected in
294: * a ContrastEnhancement, then no enhancement is performed.
295: *
296: * @return the ContrastEnhancement
297: */
298: ContrastEnhancement getContrastEnhancement();
299:
300: /**
301: * The ShadedRelief element selects the application of relief shading (or
302: * ?hill shading?) to an image for a three-dimensional visual effect. It
303: * is defined as: Exact parameters of the shading are system-dependent
304: * (for now). If the BrightnessOnly flag is ?0? (false, default), the
305: * shading is applied to the layer being rendered as the current
306: * RasterSymbol. If BrightnessOnly is ?1? (true), the shading is applied
307: * to the brightness of the colors in the rendering canvas generated so
308: * far by other layers, with the effect of relief-shading these other
309: * layers. The default for BrightnessOnly is ?0? (false). The
310: * ReliefFactor gives the amount of exaggeration to use for the height of
311: * the ?hills.? A value of around 55 (times) gives reasonable results for
312: * Earth-based DEMs. The default value is system-dependent.
313: *
314: * @param relief the shadedrelief object
315: */
316: void setShadedRelief(ShadedRelief relief);
317:
318: /**
319: * The ShadedRelief element selects the application of relief shading (or
320: * ?hill shading?) to an image for a three-dimensional visual effect. It
321: * is defined as: Exact parameters of the shading are system-dependent
322: * (for now). If the BrightnessOnly flag is ?0? (false, default), the
323: * shading is applied to the layer being rendered as the current
324: * RasterSymbol. If BrightnessOnly is ?1? (true), the shading is applied
325: * to the brightness of the colors in the rendering canvas generated so
326: * far by other layers, with the effect of relief-shading these other
327: * layers. The default for BrightnessOnly is ?0? (false). The
328: * ReliefFactor gives the amount of exaggeration to use for the height of
329: * the ?hills.? A value of around 55 (times) gives reasonable results for
330: * Earth-based DEMs. The default value is system-dependent.
331: *
332: * @return the shadedrelief object
333: */
334: ShadedRelief getShadedRelief();
335:
336: /**
337: * The ImageOutline element specifies that individual source rasters in a
338: * multi-raster set (such as a set of satellite-image scenes) should be
339: * outlined with either a LineStringSymbol or PolygonSymbol. It is defined
340: * as:
341: * <pre>
342: * <xs:element name="ImageOutline">
343: * <xs:complexType>
344: * <xs:choice>
345: * <xs:element ref="sld:LineSymbolizer"/>
346: * <xs:element ref="sld:PolygonSymbolizer"/>
347: * </xs:choice>
348: * </xs:complexType>
349: * </xs:element>
350: * </pre>
351: * An Opacity of 0.0 can be selected for the main raster to avoid rendering
352: * the main-raster pixels, or an opacity can be used for a
353: * PolygonSymbolizer Fill to allow the main-raster data be visible through
354: * the fill.
355: *
356: * @param symbolizer the symbolizer to be used. If this is <B>not</B> a
357: * polygon or a line symbolizer an unexpected argument exception
358: * may be thrown by an implementing class.
359: */
360: void setImageOutline(Symbolizer symbolizer);
361:
362: /**
363: * The ImageOutline element specifies that individual source rasters in a
364: * multi-raster set (such as a set of satellite-image scenes) should be
365: * outlined with either a LineStringSymbol or PolygonSymbol. It is
366: * defined as:
367: * <pre>
368: * <xs:element name="ImageOutline">
369: * <xs:complexType>
370: * <xs:choice>
371: * <xs:element ref="sld:LineSymbolizer"/>
372: * <xs:element ref="sld:PolygonSymbolizer"/>
373: * </xs:choice>
374: * </xs:complexType>
375: * </xs:element>
376: * </pre>
377: * An Opacity of 0.0 can be selected for the main raster to avoid rendering
378: * the main-raster pixels, or an opacity can be used for a
379: * PolygonSymbolizer Fill to allow the main-raster data be visible through
380: * the fill.
381: *
382: * @return The relevent symbolizer
383: */
384: Symbolizer getImageOutline();
385: }
|