org.apache.xmlgraphics.image.codec.png.PNGDecodeParam Maven / Gradle / Ivy
Show all versions of xmlgraphics-commons Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/* $Id: PNGDecodeParam.java 1732018 2016-02-24 04:51:06Z gadams $ */
package org.apache.xmlgraphics.image.codec.png;
import org.apache.xmlgraphics.image.codec.util.ImageDecodeParam;
import org.apache.xmlgraphics.image.codec.util.PropertyUtil;
// CSOFF: WhitespaceAround
/**
* An instance of ImageDecodeParam for decoding images in
* the PNG format.
*
* PNGDecodeParam allows several aspects of the decoding
* process for PNG images to be controlled. By default, decoding produces
* output images with the following properties:
*
* Images with a bit depth of 8 or less use a
* DataBufferByte to hold the pixel data. 16-bit images
* use a DataBufferUShort.
*
*
Palette color images and non-transparent grayscale images with
* bit depths of 1, 2, or 4 will have a
* MultiPixelPackedSampleModel and an
* IndexColorModel. For palette color images, the
* ColorModel palette contains the red, green, blue, and
* optionally alpha palette information. For grayscale images, the
* palette is used to expand the pixel data to cover the range 0-255.
* The pixels are stored packed 8, 4, or 2 to the byte.
*
*
All other images are stored using a
* PixelInterleavedSampleModel with each sample of a pixel
* occupying its own byte or short within
* the DataBuffer. A ComponentColorModel is
* used which simply extracts the red, green, blue, gray, and/or alpha
* information from separate DataBuffer entries.
*
*
Five aspects of this process may be altered by means of methods
* in this class.
*
*
setSuppressAlpha() prevents an alpha channel
* from appearing in the output.
*
*
setExpandPalette() turns palette-color images into
* 3-or 4-channel full-color images.
*
*
setOutput8BitGray() causes 1, 2, or 4 bit
* grayscale images to be output in 8-bit form, using a
* ComponentSampleModel and
* ComponentColorModel.
*
*
setDecodingExponent() causes the output image to be
* gamma-corrected using a supplied output gamma value.
*
*
setExpandGrayAlpha() causes 2-channel gray/alpha
* (GA) images to be output as full-color (GGGA) images, which may
* simplify further processing and display.
*
*
This class is not a committed part of the JAI API. It may
* be removed or changed in future releases of JAI.
*/
public class PNGDecodeParam implements ImageDecodeParam {
private static final long serialVersionUID = 3957265194926624623L;
/**
* Constructs a default instance of PNGDecodeParam.
*/
public PNGDecodeParam() { }
private boolean suppressAlpha;
/**
* Returns true if alpha (transparency) will
* be prevented from appearing in the output.
*/
public boolean getSuppressAlpha() {
return suppressAlpha;
}
/**
* If set, no alpha (transparency) channel will appear in the
* output image.
*
*
The default is to allow transparency to appear in the
* output image.
*/
public void setSuppressAlpha(boolean suppressAlpha) {
this.suppressAlpha = suppressAlpha;
}
private boolean expandPalette;
/**
* Returns true if palette-color images will be expanded to
* produce full-color output.
*/
public boolean getExpandPalette() {
return expandPalette;
}
/**
* If set, palette color images (PNG color type 3) will
* be decoded into full-color (RGB) output images. The output
* image may have 3 or 4 channels, depending on the presence of
* transparency information.
*
*
The default is to output palette images using a single
* channel. The palette information is used to construct the
* output image's ColorModel.
*/
public void setExpandPalette(boolean expandPalette) {
this.expandPalette = expandPalette;
}
private boolean output8BitGray;
/**
* Returns the current value of the 8-bit gray output parameter.
*/
public boolean getOutput8BitGray() {
return output8BitGray;
}
/**
* If set, grayscale images with a bit depth less than 8
* (1, 2, or 4) will be output in 8 bit form. The output values
* will occupy the full 8-bit range. For example, gray values
* 0, 1, 2, and 3 of a 2-bit image will be output as
* 0, 85, 170, and 255.
*
*
The decoding of non-grayscale images and grayscale images
* with a bit depth of 8 or 16 are unaffected by this setting.
*
*
The default is not to perform expansion. Grayscale images
* with a depth of 1, 2, or 4 bits will be represented using
* a MultiPixelPackedSampleModel and an
* IndexColorModel.
*/
public void setOutput8BitGray(boolean output8BitGray) {
this.output8BitGray = output8BitGray;
}
private boolean performGammaCorrection = true;
/**
* Returns true if gamma correction is to be performed
* on the image data. The default is true.
*
*
If gamma correction is to be performed, the
* getUserExponent() and
* getDisplayExponent() methods are used in addition to
* the gamma value stored within the file (or the default value of
* 1/2.2 used if no value is found) to produce a single exponent
* using the formula:
*
* decoding_exponent = user_exponent/(gamma_from_file * display_exponent)
*
*/
public boolean getPerformGammaCorrection() {
return performGammaCorrection;
}
/**
* Turns gamma corection of the image data on or off.
*/
public void setPerformGammaCorrection(boolean performGammaCorrection) {
this.performGammaCorrection = performGammaCorrection;
}
private float userExponent = 1.0F;
/**
* Returns the current value of the user exponent parameter.
* By default, the user exponent is equal to 1.0F.
*/
public float getUserExponent() {
return userExponent;
}
/**
* Sets the user exponent to a given value. The exponent
* must be positive. If not, an
* IllegalArgumentException will be thrown.
*
* The output image pixels will be placed through a transformation
* of the form:
*
*
* sample = integer_sample / (2^bitdepth - 1.0)
* decoding_exponent = user_exponent/(gamma_from_file * display_exponent)
* output = sample ^ decoding_exponent
*
*
* where gamma_from_file is the gamma of the file
* data, as determined by the gAMA, sRGB,
* and/or iCCP chunks, and display_exponent
* is the exponent of the intrinsic transfer curve of the display,
* generally 2.2.
*
* Input files which do not specify any gamma are assumed to
* have a gamma of 1/2.2; such images may be displayed
* on a CRT with an exponent of 2.2 using the default user
* exponent of 1.0.
*
*
The user exponent may be used in order to change the
* effective gamma of a file. If a file has a stored gamma of
* X, but the decoder believes that the true file gamma is Y,
* setting a user exponent of Y/X will produce the same result
* as changing the file gamma.
*
*
This parameter affects the decoding of all image types.
*
* @throws IllegalArgumentException if userExponent is
* negative.
*/
public void setUserExponent(float userExponent) {
if (userExponent <= 0.0F) {
throw new IllegalArgumentException(PropertyUtil.getString("PNGDecodeParam0"));
}
this.userExponent = userExponent;
}
private float displayExponent = 2.2F;
/**
* Returns the current value of the display exponent parameter.
* By default, the display exponent is equal to 2.2F.
*/
public float getDisplayExponent() {
return displayExponent;
}
/**
* Sets the display exponent to a given value. The exponent
* must be positive. If not, an
* IllegalArgumentException will be thrown.
*
*
The output image pixels will be placed through a transformation
* of the form:
*
*
* sample = integer_sample / (2^bitdepth - 1.0)
* decoding_exponent = user_exponent/(gamma_from_file * display_exponent)
* output = sample ^ decoding_exponent
*
*
* where gamma_from_file is the gamma of the file
* data, as determined by the gAMA, sRGB,
* and/or iCCP chunks, and user_exponent
* is an additional user-supplied parameter.
*
* Input files which do not specify any gamma are assumed to
* have a gamma of 1/2.2; such images should be
* decoding using the default display exponent of 2.2.
*
*
If an image is to be processed further before being displayed,
* it may be preferable to set the display exponent to 1.0 in order
* to produce a linear output image.
*
*
This parameter affects the decoding of all image types.
*
* @throws IllegalArgumentException if userExponent is
* negative.
*/
public void setDisplayExponent(float displayExponent) {
if (displayExponent <= 0.0F) {
throw new IllegalArgumentException(PropertyUtil.getString("PNGDecodeParam1"));
}
this.displayExponent = displayExponent;
}
private boolean expandGrayAlpha;
/**
* Returns the current setting of the gray/alpha expansion.
*/
public boolean getExpandGrayAlpha() {
return expandGrayAlpha;
}
/**
* If set, images containing one channel of gray and one channel of
* alpha (GA) will be output in a 4-channel format (GGGA). This
* produces output that may be simpler to process and display.
*
*
This setting affects both images of color type 4 (explicit
* alpha) and images of color type 0 (grayscale) that contain
* transparency information.
*
*
By default, no expansion is performed.
*/
public void setExpandGrayAlpha(boolean expandGrayAlpha) {
this.expandGrayAlpha = expandGrayAlpha;
}
private boolean generateEncodeParam;
private PNGEncodeParam encodeParam;
/**
* Returns true if an instance of
* PNGEncodeParam will be available after an image
* has been decoded via the getEncodeParam method.
*/
public boolean getGenerateEncodeParam() {
return generateEncodeParam;
}
/**
* If set, an instance of PNGEncodeParam will be
* available after an image has been decoded via the
* getEncodeParam method that encapsulates information
* about the contents of the PNG file. If not set, this information
* will not be recorded and getEncodeParam() will
* return null.
*/
public void setGenerateEncodeParam(boolean generateEncodeParam) {
this.generateEncodeParam = generateEncodeParam;
}
/**
* If getGenerateEncodeParam() is true,
* this method may be called after decoding has completed, and
* will return an instance of PNGEncodeParam containing
* information about the contents of the PNG file just decoded.
*/
public PNGEncodeParam getEncodeParam() {
return encodeParam;
}
/**
* Sets the current encoder param instance. This method is
* intended to be called by the PNG decoder and will overwrite the
* current instance returned by getEncodeParam.
*/
public void setEncodeParam(PNGEncodeParam encodeParam) {
this.encodeParam = encodeParam;
}
}