001 /*----------------------------------------------------------------------------*/
002 /* Copyright (c) FIRST 2008-2012. All Rights Reserved. */
003 /* Open Source Software - may be modified and shared by FRC teams. The code */
004 /* must be accompanied by the FIRST BSD license file in the root directory of */
005 /* the project. */
006 /*----------------------------------------------------------------------------*/
007 package edu.wpi.first.wpilibj.image;
008
009 /**
010 * A class representing a color image.
011 * @author dtjones
012 */
013 public abstract class ColorImage extends Image {
014
015 ColorImage(NIVision.ImageType type) throws NIVisionException {
016 super(type);
017 }
018
019 ColorImage(ColorImage sourceImage) {
020 super(sourceImage);
021 }
022
023 private BinaryImage threshold(NIVision.ColorMode colorMode,
024 int low1, int high1,
025 int low2, int high2,
026 int low3, int high3) throws NIVisionException {
027 BinaryImage res = new BinaryImage();
028 NIVision.Range range1 = new NIVision.Range(low1, high1);
029 NIVision.Range range2 = new NIVision.Range(low2, high2);
030 NIVision.Range range3 = new NIVision.Range(low3, high3);
031 try {
032 NIVision.colorThreshold(res.image, image, colorMode, range1.getPointer(), range2.getPointer(), range3.getPointer());
033 } catch (NIVisionException e) {
034 res.free();
035 throw e;
036 } finally {
037 range1.free();
038 range2.free();
039 range3.free();
040 }
041 return res;
042 }
043
044 /**
045 * Return a mask of the areas of the image that fall within the given ranges for color values
046 * @param redLow The lower red limit.
047 * @param redHigh The upper red limit.
048 * @param greenLow The lower green limit.
049 * @param greenHigh The upper green limit.
050 * @param blueLow The lower blue limit.
051 * @param blueHigh The upper blue limit.
052 * @return A BinaryImage masking the areas which match the given thresholds.
053 */
054 public BinaryImage thresholdRGB(int redLow, int redHigh, int greenLow, int greenHigh, int blueLow, int blueHigh) throws NIVisionException {
055 return threshold(NIVision.ColorMode.IMAQ_RGB, redLow, redHigh, greenLow, greenHigh, blueLow, blueHigh);
056 }
057
058 /**
059 * Return a mask of the areas of the image that fall within the given ranges for color values
060 * @param hueLow The lower hue limit.
061 * @param hueHigh The upper hue limit.
062 * @param saturationLow The lower saturation limit.
063 * @param saturationHigh The upper saturation limit.
064 * @param luminenceLow The lower luminence limit.
065 * @param luminenceHigh The upper luminence limit.
066 * @return A BinaryImage masking the areas which match the given thresholds.
067 */
068 public BinaryImage thresholdHSL(int hueLow, int hueHigh, int saturationLow, int saturationHigh, int luminenceLow, int luminenceHigh) throws NIVisionException {
069 return threshold(NIVision.ColorMode.IMAQ_HSL, hueLow, hueHigh, saturationLow, saturationHigh, luminenceLow, luminenceHigh);
070 }
071
072 /**
073 * Return a mask of the areas of the image that fall within the given ranges for color values
074 * @param hueLow The lower hue limit.
075 * @param hueHigh The upper hue limit.
076 * @param saturationLow The lower saturation limit.
077 * @param saturationHigh The upper saturation limit.
078 * @param valueHigh The lower value limit.
079 * @param valueLow The upper value limit.
080 * @return A BinaryImage masking the areas which match the given thresholds.
081 */
082 public BinaryImage thresholdHSV(int hueLow, int hueHigh, int saturationLow, int saturationHigh, int valueLow, int valueHigh) throws NIVisionException {
083 return threshold(NIVision.ColorMode.IMAQ_HSV, hueLow, hueHigh, saturationLow, saturationHigh, valueLow, valueHigh);
084 }
085
086 /**
087 * Return a mask of the areas of the image that fall within the given ranges for color values
088 * @param hueLow The lower hue limit.
089 * @param hueHigh The upper hue limit.
090 * @param saturationLow The lower saturation limit.
091 * @param saturationHigh The upper saturation limit.
092 * @param intansityLow The lower intensity limit.
093 * @param intensityHigh The upper intensity limit.
094 * @return A BinaryImage masking the areas which match the given thresholds.
095 */
096 public BinaryImage thresholdHSI(int hueLow, int hueHigh, int saturationLow, int saturationHigh, int intansityLow, int intensityHigh) throws NIVisionException {
097 return threshold(NIVision.ColorMode.IMAQ_HSI, hueLow, hueHigh, saturationLow, saturationHigh, intansityLow, intensityHigh);
098 }
099
100 MonoImage extractFirstColorPlane(NIVision.ColorMode mode) throws NIVisionException {
101 MonoImage result = new MonoImage();
102 try {
103 NIVision.extractColorPlanes(image, mode, result.image, null, null);
104 } catch (NIVisionException e) {
105 result.free();
106 throw e;
107 }
108 return result;
109 }
110
111 MonoImage extractSecondColorPlane(NIVision.ColorMode mode) throws NIVisionException {
112 MonoImage result = new MonoImage();
113 try {
114 NIVision.extractColorPlanes(image, mode, null, result.image, null);
115 } catch (NIVisionException e) {
116 result.free();
117 throw e;
118 }
119 return result;
120 }
121
122 MonoImage extractThirdColorPlane(NIVision.ColorMode mode) throws NIVisionException {
123 MonoImage result = new MonoImage();
124 try {
125 NIVision.extractColorPlanes(image, mode, null, null, result.image);
126 } catch (NIVisionException e) {
127 result.free();
128 throw e;
129 }
130 return result;
131 }
132
133 /**
134 * Get the red color plane from the image when represented in RGB color space.
135 * @return The red color plane from the image.
136 */
137 public MonoImage getRedPlane() throws NIVisionException {
138 return extractFirstColorPlane(NIVision.ColorMode.IMAQ_RGB);
139 }
140
141 /**
142 * Get the green color plane from the image when represented in RGB color space.
143 * @return The green color plane from the image.
144 */
145 public MonoImage getGreenPlane() throws NIVisionException {
146 return extractSecondColorPlane(NIVision.ColorMode.IMAQ_RGB);
147 }
148
149 /**
150 * Get the blue color plane from the image when represented in RGB color space.
151 * @return The blue color plane from the image.
152 */
153 public MonoImage getBluePlane() throws NIVisionException {
154 return extractThirdColorPlane(NIVision.ColorMode.IMAQ_RGB);
155 }
156
157 /**
158 * Get the hue color plane from the image when represented in HSL color space.
159 * @return The hue color plane from the image.
160 */
161 public MonoImage getHSLHuePlane() throws NIVisionException {
162 return extractFirstColorPlane(NIVision.ColorMode.IMAQ_HSL);
163 }
164
165 /**
166 * Get the hue color plane from the image when represented in HSV color space.
167 * @return The hue color plane from the image.
168 */
169 public MonoImage getHSVHuePlane() throws NIVisionException {
170 return extractFirstColorPlane(NIVision.ColorMode.IMAQ_HSV);
171 }
172
173 /**
174 * Get the hue color plane from the image when represented in HSI color space.
175 * @return The hue color plane from the image.
176 */
177 public MonoImage getHSIHuePlane() throws NIVisionException {
178 return extractFirstColorPlane(NIVision.ColorMode.IMAQ_HSI);
179 }
180
181 /**
182 * Get the saturation color plane from the image when represented in HSL color space.
183 * @return The saturation color plane from the image.
184 */
185 public MonoImage getHSLSaturationPlane() throws NIVisionException {
186 return extractSecondColorPlane(NIVision.ColorMode.IMAQ_HSL);
187 }
188
189 /**
190 * Get the saturation color plane from the image when represented in HSV color space.
191 * @return The saturation color plane from the image.
192 */
193 public MonoImage getHSVSaturationPlane() throws NIVisionException {
194 return extractSecondColorPlane(NIVision.ColorMode.IMAQ_HSV);
195 }
196
197 /**
198 * Get the saturation color plane from the image when represented in HSI color space.
199 * @return The saturation color plane from the image.
200 */
201 public MonoImage getHSISaturationPlane() throws NIVisionException {
202 return extractSecondColorPlane(NIVision.ColorMode.IMAQ_HSI);
203 }
204
205 /**
206 * Get the luminance color plane from the image when represented in HSL color space.
207 * @return The luminance color plane from the image.
208 */
209 public MonoImage getLuminancePlane() throws NIVisionException {
210 return extractThirdColorPlane(NIVision.ColorMode.IMAQ_HSL);
211 }
212
213 /**
214 * Get the value color plane from the image when represented in HSV color space.
215 * @return The value color plane from the image.
216 */
217 public MonoImage getValuePlane() throws NIVisionException {
218 return extractThirdColorPlane(NIVision.ColorMode.IMAQ_HSV);
219 }
220
221 /**
222 * Get the intensity color plane from the image when represented in HSI color space.
223 * @return The intensity color plane from the image.
224 */
225 public MonoImage getIntensityPlane() throws NIVisionException {
226 return extractThirdColorPlane(NIVision.ColorMode.IMAQ_HSI);
227 }
228
229 ColorImage replaceFirstColorPlane(NIVision.ColorMode mode, MonoImage plane) throws NIVisionException {
230 NIVision.replaceColorPlanes(image, image, mode, plane.image, null, null);
231 return this;
232 }
233
234 ColorImage replaceSecondColorPlane(NIVision.ColorMode mode, MonoImage plane) throws NIVisionException {
235 NIVision.replaceColorPlanes(image, image, mode, null, plane.image, null);
236 return this;
237 }
238
239 ColorImage replaceThirdColorPlane(NIVision.ColorMode mode, MonoImage plane) throws NIVisionException {
240 NIVision.replaceColorPlanes(image, image, mode, null, null, plane.image);
241 return this;
242 }
243
244 /**
245 * Set the red color plane from the image when represented in RGB color space.
246 * This does not create a new image, but modifies this one instead. Create a
247 * copy before hand if you need to continue using the original.
248 * @param plane The MonoImage representing the new color plane.
249 * @return The resulting image.
250 */
251 public ColorImage replaceRedPlane(MonoImage plane) throws NIVisionException {
252 return replaceFirstColorPlane(NIVision.ColorMode.IMAQ_RGB, plane);
253 }
254
255 /**
256 * Set the green color plane from the image when represented in RGB color space.
257 * This does not create a new image, but modifies this one instead. Create a
258 * copy before hand if you need to continue using the original.
259 * @param plane The MonoImage representing the new color plane.
260 * @return The resulting image.
261 */
262 public ColorImage replaceGreenPlane(MonoImage plane) throws NIVisionException {
263 return replaceSecondColorPlane(NIVision.ColorMode.IMAQ_RGB, plane);
264 }
265
266 /**
267 * Set the blue color plane from the image when represented in RGB color space.
268 * This does not create a new image, but modifies this one instead. Create a
269 * copy before hand if you need to continue using the original.
270 * @param plane The MonoImage representing the new color plane.
271 * @return The resulting image.
272 */
273 public ColorImage replaceBluePlane(MonoImage plane) throws NIVisionException {
274 return replaceThirdColorPlane(NIVision.ColorMode.IMAQ_RGB, plane);
275 }
276
277 /**
278 * Set the hue color plane from the image when represented in HSL color space.
279 * This does not create a new image, but modifies this one instead. Create a
280 * copy before hand if you need to continue using the original.
281 * @param plane The MonoImage representing the new color plane.
282 * @return The resulting image.
283 */
284 public ColorImage replaceHSLHuePlane(MonoImage plane) throws NIVisionException {
285 return replaceFirstColorPlane(NIVision.ColorMode.IMAQ_HSL, plane);
286 }
287
288 /**
289 * Set the hue color plane from the image when represented in HSV color space.
290 * This does not create a new image, but modifies this one instead. Create a
291 * copy before hand if you need to continue using the original.
292 * @param plane The MonoImage representing the new color plane.
293 * @return The resulting image.
294 */
295 public ColorImage replaceHSVHuePlane(MonoImage plane) throws NIVisionException {
296 return replaceFirstColorPlane(NIVision.ColorMode.IMAQ_HSV, plane);
297 }
298
299 /**
300 * Set the hue color plane from the image when represented in HSI color space.
301 * This does not create a new image, but modifies this one instead. Create a
302 * copy before hand if you need to continue using the original.
303 * @param plane The MonoImage representing the new color plane.
304 * @return The resulting image.
305 */
306 public ColorImage replaceHSIHuePlane(MonoImage plane) throws NIVisionException {
307 return replaceFirstColorPlane(NIVision.ColorMode.IMAQ_HSI, plane);
308 }
309
310 /**
311 * Set the saturation color plane from the image when represented in HSL color space.
312 * This does not create a new image, but modifies this one instead. Create a
313 * copy before hand if you need to continue using the original.
314 * @param plane The MonoImage representing the new color plane.
315 * @return The resulting image.
316 */
317 public ColorImage replaceHSLSaturationPlane(MonoImage plane) throws NIVisionException {
318 return replaceSecondColorPlane(NIVision.ColorMode.IMAQ_HSL, plane);
319 }
320
321 /**
322 * Set the saturation color plane from the image when represented in HSV color space.
323 * This does not create a new image, but modifies this one instead. Create a
324 * copy before hand if you need to continue using the original.
325 * @param plane The MonoImage representing the new color plane.
326 * @return The resulting image.
327 */
328 public ColorImage replaceHSVSaturationPlane(MonoImage plane) throws NIVisionException {
329 return replaceSecondColorPlane(NIVision.ColorMode.IMAQ_HSV, plane);
330 }
331
332 /**
333 * Set the saturation color plane from the image when represented in HSI color space.
334 * This does not create a new image, but modifies this one instead. Create a
335 * copy before hand if you need to continue using the original.
336 * @param plane The MonoImage representing the new color plane.
337 * @return The resulting image.
338 */
339 public ColorImage replaceHSISaturationPlane(MonoImage plane) throws NIVisionException {
340 return replaceSecondColorPlane(NIVision.ColorMode.IMAQ_HSI, plane);
341 }
342
343 /**
344 * Set the luminance color plane from the image when represented in HSL color space.
345 * This does not create a new image, but modifies this one instead. Create a
346 * copy before hand if you need to continue using the original.
347 * @param plane The MonoImage representing the new color plane.
348 * @return The resulting image.
349 */
350 public ColorImage replaceLuminancePlane(MonoImage plane) throws NIVisionException {
351 return replaceThirdColorPlane(NIVision.ColorMode.IMAQ_HSL, plane);
352 }
353
354 /**
355 * Set the value color plane from the image when represented in HSV color space.
356 * This does not create a new image, but modifies this one instead. Create a
357 * copy before hand if you need to continue using the original.
358 * @param plane The MonoImage representing the new color plane.
359 * @return The resulting image.
360 */
361 public ColorImage replaceValuePlane(MonoImage plane) throws NIVisionException {
362 return replaceThirdColorPlane(NIVision.ColorMode.IMAQ_HSV, plane);
363 }
364
365 /**
366 * Set the intensity color plane from the image when represented in HSI color space.
367 * This does not create a new image, but modifies this one instead. Create a
368 * copy before hand if you need to continue using the original.
369 * @param plane The MonoImage representing the new color plane.
370 * @return The resulting image.
371 */
372 public ColorImage replaceIntensityPlane(MonoImage plane) throws NIVisionException {
373 return replaceThirdColorPlane(NIVision.ColorMode.IMAQ_HSI, plane);
374 }
375
376 /**
377 * Calculates the histogram of each plane of a color image and redistributes
378 * pixel values across the desired range while maintaining pixel value
379 * groupings.
380 * This does not create a new image, but modifies this one instead. Create a
381 * copy before hand if you need to continue using the original.
382 * @return The modified image.
383 */
384 public ColorImage colorEqualize() throws NIVisionException {
385 NIVision.colorEqualize(image, image, true);
386 return this;
387 }
388
389 /**
390 * Calculates the histogram of each plane of a color image and redistributes
391 * pixel values across the desired range while maintaining pixel value
392 * groupings for the Luminance plane only.
393 * This does not create a new image, but modifies this one instead. Create a
394 * copy before hand if you need to continue using the original.
395 * @return The modified image.
396 */
397 public ColorImage luminanceEqualize() throws NIVisionException {
398 NIVision.colorEqualize(image, image, false);
399 return this;
400 }
401 }