javax.media.jai.operator
Class IIPDescriptor

java.lang.Object
  extended byjavax.media.jai.OperationDescriptorImpl
      extended byjavax.media.jai.operator.IIPDescriptor
All Implemented Interfaces:
OperationDescriptor, RegistryElementDescriptor, Serializable

public class IIPDescriptor
extends OperationDescriptorImpl

An OperationDescriptor describing the "IIP" operation.

This operation provides client-side support of the Internet Imaging Protocol (IIP) in both the rendered and renderable modes. It creates a java.awt.image.RenderedImage or a java.awt.image.renderable.RenderableImage based on the data received from the IIP server, and optionally applies a sequence of operations to the created image.

The operations that may be applied and the order in which they are applied are defined in section 2.2.1.1 of the Internet Imaging Protocol Specification version 1.0.5. Some or all of the requested operations may be executed on the IIP server if it is determined that the server supports such operations. Any of the requested operations not supported by the server will be executed on the host on which the operation chain is rendered.

The processing sequence for the supplied operations is as follows:

As indicated, the rendering transformation is performed only in renderable mode processing. This transformation is derived from the AffineTransform supplied in the RenderContext when rendering actually occurs. Rendered mode processing creates a RenderedImage which is the default rendering of the RenderableImage created in renderable mode processing.

The "URL" parameter specifies the URL of the IIP image as a java.lang.String. It must represent a valid URL, and include any required FIF or SDS commands. It cannot be null.

The "subImages" parameter optionally indicates the sub-images to be used by the server to get the images at each resolution level. The values in this int array cannot be negative. If this parameter is not specified, or if the array is too short (length is 0), or if a negative value is specified, then this operation will use the zeroth sub-image of the resolution level actually processed.

The "filter" parameter specifies a blur or sharpen operation: a positive value indicates sharpen and a negative value blur. A unit step should produce a perceptible change in the image. The default value is 0 which signifies that no filtering will occur.

The "colorTwist" parameter represents a 4x4 matrix stored in row-major order and should have an array length of at least 16. If an array of length greater than 16 is specified, all elements from index 16 and beyond are ignored. Elements 12, 13 and 14 must be 0. This matrix will be applied to the (possibly padded) data in an intermediate normalized PhotoYCC color space with a premultiplied alpha channel. This operation will force an alpha channel to be added to the image if the last column of the last row of the color twist matrix is not 1.0F. Also, if the image originally has a grayscale color space it will be cast up to RGB if casting the data back to grayscale after applying the color twist matrix would result in any loss of data.

The "contrast" parameter specifies a contrast enhancement operation with increasing contrast for larger value. It must be greater than or equal to 1.0F. A value of 1.0F indicates no contrast adjustment.

The "sourceROI" parameter specifies the rectangle of interest in the source image in rendering-independent coordinates. The intersection of this rectangle with the rendering-independent bounds of the source image must equal itself. The rendering-independent bounds of the source image are defined to be (0.0F, 0.0F, r, 1.0F) where r is the aspect ratio (width/height) of the source image. Note that the source image will not in fact be cropped to these limits but values outside of this rectangle will be suppressed.

The "transform" parameter represents an affine backward mapping to be applied in rendering-independent coordinates. Note that the direction of transformation is opposite to that of the AffineTransform supplied in the RenderContext which is a forward mapping. The default value of this transform is the identity mapping. The supplied AffineTransform must be invertible.

The "aspectRatio" parameter specifies the rendering-independent width of the destination image and must be positive. The rendering-independent bounds of the destination image are (0.0F, 0.0F, aspectRatio, 1.0F). If this parameter is not provided the destination aspect ratio defaults to that of the source.

The "destROI" parameter specifies the rectangle of interest in the destination image in rendering-independent coordinates. This rectangle must have a non-empty intersection with the rendering-independent bounds of the destination image but is not constrained to the destination image bounds.

A counterclockwise rotation may be applied to the destination image. However, the angle is limited to 0, 90, 180, or 270 degrees. By default, the destination image is not rotated.

The "mirrorAxis" parameter may be null, in which case no flipping is applied, or a String of "x", "X", "y", or "Y".

The "ICCProfile" parameter may only be used with client-side processing or with server-side processing if the connection protocol supports the ability to transfer a profile.

The "JPEGQuality" and "JPEGTable" parameters are only used with server-side processing. If provided, JPEGQuality must be in the range [0,100] and JPEGTable in [1,255].

There is no source image associated with this operation.

Resource List
Name Value
GlobalName IIP
LocalName IIP
Vendor com.sun.media.jai
Description Provides client support of the Internet Imaging Protocol in the rendered and renderable modes.
DocURL http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/IIPDescriptor.html
Version 1.0
arg0Desc The URL of the IIP image.
arg1Desc The sub-images to be used by the server for images at each resolution level.
arg2Desc The filtering value.
arg3Desc The color twist matrix.
arg4Desc The contrast value.
arg5Desc The source rectangle of interest in rendering-independent coordinates.
arg6Desc The rendering-independent spatial orientation transform.
arg7Desc The aspect ratio of the destination image.
arg8Desc The destination rectangle of interest in rendering-independent coordinates.
arg9Desc The counterclockwise rotation angle to be applied to the destination.
arg10Desc The mirror axis.
arg11Desc The ICC profile used to represent the color space of the source image.
arg12Desc The JPEG quality factor.
arg13Desc The JPEG compression group index number.

Parameter List
Name Class Type Default Value
URL java.lang.String NO_PARAMETER_DEFAULT
subImages int[] { 0 }
filter java.lang.Float 0.0F
colorTwist float[] null
contrast java.lang.Float 1.0F
sourceROI java.awt.geom.Rectangle2D.Float null
transform java.awt.geom.AffineTransform identity transform
aspectRatio java.lang.Float null
destROI java.awt.geom.Rectangle2D.Float null
rotation java.lang.Integer 0
mirrorAxis java.lang.String null
ICCProfile java.awt.color.ICC_Profile null
JPEGQuality java.lang.Integer null
JPEGTable java.lang.Integer null

See Also:
Digital Imaging Group, RenderedImage, RenderableImage, IIPResolutionDescriptor, Serialized Form

Field Summary
 
Fields inherited from class javax.media.jai.OperationDescriptorImpl
sourceNames, supportedModes
 
Fields inherited from interface javax.media.jai.OperationDescriptor
NO_PARAMETER_DEFAULT
 
Constructor Summary
IIPDescriptor()
          Constructor.
 
Method Summary
static RenderedOp create(String URL, int[] subImages, Float filter, float[] colorTwist, Float contrast, Rectangle2D.Float sourceROI, AffineTransform transform, Float aspectRatio, Rectangle2D.Float destROI, Integer rotation, String mirrorAxis, ICC_Profile ICCProfile, Integer JPEGQuality, Integer JPEGTable, RenderingHints hints)
          Provides client support of the Internet Imaging Protocol in the rendered and renderable mode.
static RenderableOp createRenderable(String URL, int[] subImages, Float filter, float[] colorTwist, Float contrast, Rectangle2D.Float sourceROI, AffineTransform transform, Float aspectRatio, Rectangle2D.Float destROI, Integer rotation, String mirrorAxis, ICC_Profile ICCProfile, Integer JPEGQuality, Integer JPEGTable, RenderingHints hints)
          Provides client support of the Internet Imaging Protocol in the rendered and renderable mode.
 Number getParamMaxValue(int index)
          Returns the maximum legal value of a specified numeric parameter for this operation.
 Number getParamMinValue(int index)
          Returns the minimum legal value of a specified numeric parameter for this operation.
 boolean isRenderableSupported()
          Overrides super class's default implementation to return true because this operation supports renderable mode.
protected  boolean validateParameters(ParameterBlock args, StringBuffer msg)
          Validates the input parameters.
 
Methods inherited from class javax.media.jai.OperationDescriptorImpl
arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IIPDescriptor

public IIPDescriptor()
Constructor.

Method Detail

isRenderableSupported

public boolean isRenderableSupported()
Overrides super class's default implementation to return true because this operation supports renderable mode.

Specified by:
isRenderableSupported in interface OperationDescriptor
Overrides:
isRenderableSupported in class OperationDescriptorImpl
See Also:
OperationDescriptorImpl.isModeSupported(java.lang.String)

getParamMinValue

public Number getParamMinValue(int index)
Returns the minimum legal value of a specified numeric parameter for this operation. If the supplied index does not correspond to a numeric parameter, this method returns null.

Specified by:
getParamMinValue in interface OperationDescriptor
Overrides:
getParamMinValue in class OperationDescriptorImpl
Parameters:
index - The index of the parameter to be queried.
Returns:
A Number representing the minimum legal value, or null if the specified parameter is not numeric.
Throws:
ArrayIndexOutOfBoundsException - if index is less than 0 or greater than 13.
See Also:
ParameterListDescriptor.getParamValueRange(java.lang.String), ParameterListDescriptor.getEnumeratedParameterValues(java.lang.String), ParameterListDescriptor.isParameterValueValid(java.lang.String, java.lang.Object)

getParamMaxValue

public Number getParamMaxValue(int index)
Returns the maximum legal value of a specified numeric parameter for this operation. If the supplied index does not correspond to a numeric parameter, this method returns null.

Specified by:
getParamMaxValue in interface OperationDescriptor
Overrides:
getParamMaxValue in class OperationDescriptorImpl
Parameters:
index - The index of the parameter to be queried.
Returns:
A Number representing the maximum legal value, or null if the specified parameter is not numeric.
Throws:
ArrayIndexOutOfBoundsException - if index is less than 0 or greater than 13.
See Also:
ParameterListDescriptor.getParamValueRange(java.lang.String), ParameterListDescriptor.getEnumeratedParameterValues(java.lang.String), ParameterListDescriptor.isParameterValueValid(java.lang.String, java.lang.Object)

validateParameters

protected boolean validateParameters(ParameterBlock args,
                                     StringBuffer msg)
Validates the input parameters.

In addition to the standard checks performed by the superclass method, this method checks that:

Overrides:
validateParameters in class OperationDescriptorImpl
See Also:
OperationDescriptorImpl.validateParameters(java.lang.String, java.awt.image.renderable.ParameterBlock, java.lang.StringBuffer)

create

public static RenderedOp create(String URL,
                                int[] subImages,
                                Float filter,
                                float[] colorTwist,
                                Float contrast,
                                Rectangle2D.Float sourceROI,
                                AffineTransform transform,
                                Float aspectRatio,
                                Rectangle2D.Float destROI,
                                Integer rotation,
                                String mirrorAxis,
                                ICC_Profile ICCProfile,
                                Integer JPEGQuality,
                                Integer JPEGTable,
                                RenderingHints hints)
Provides client support of the Internet Imaging Protocol in the rendered and renderable mode.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:
URL - The URL of the IIP image.
subImages - The sub-images to be used by the server for images at each resolution level. May be null.
filter - The filtering value. May be null.
colorTwist - The color twist matrix. May be null.
contrast - The contrast value. May be null.
sourceROI - The source rectangle of interest in rendering-independent coordinates. May be null.
transform - The rendering-independent spatial orientation transform. May be null.
aspectRatio - The aspect ratio of the destination image. May be null.
destROI - The destination rectangle of interest in rendering-independent coordinates. May be null.
rotation - The counterclockwise rotation angle to be applied to the destination. May be null.
mirrorAxis - The mirror axis. May be null.
ICCProfile - The ICC profile used to represent the color space of the source image. May be null.
JPEGQuality - The JPEG quality factor. May be null.
JPEGTable - The JPEG compression group index number. May be null.
hints - The RenderingHints to use. May be null.
Returns:
The RenderedOp destination.
Throws:
IllegalArgumentException - if URL is null.
See Also:
JAI, ParameterBlockJAI, RenderedOp

createRenderable

public static RenderableOp createRenderable(String URL,
                                            int[] subImages,
                                            Float filter,
                                            float[] colorTwist,
                                            Float contrast,
                                            Rectangle2D.Float sourceROI,
                                            AffineTransform transform,
                                            Float aspectRatio,
                                            Rectangle2D.Float destROI,
                                            Integer rotation,
                                            String mirrorAxis,
                                            ICC_Profile ICCProfile,
                                            Integer JPEGQuality,
                                            Integer JPEGTable,
                                            RenderingHints hints)
Provides client support of the Internet Imaging Protocol in the rendered and renderable mode.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.createRenderable(String,ParameterBlock,RenderingHints).

Parameters:
URL - The URL of the IIP image.
subImages - The sub-images to be used by the server for images at each resolution level. May be null.
filter - The filtering value. May be null.
colorTwist - The color twist matrix. May be null.
contrast - The contrast value. May be null.
sourceROI - The source rectangle of interest in rendering-independent coordinates. May be null.
transform - The rendering-independent spatial orientation transform. May be null.
aspectRatio - The aspect ratio of the destination image. May be null.
destROI - The destination rectangle of interest in rendering-independent coordinates. May be null.
rotation - The counterclockwise rotation angle to be applied to the destination. May be null.
mirrorAxis - The mirror axis. May be null.
ICCProfile - The ICC profile used to represent the color space of the source image. May be null.
JPEGQuality - The JPEG quality factor. May be null.
JPEGTable - The JPEG compression group index number. May be null.
hints - The RenderingHints to use. May be null.
Returns:
The RenderableOp destination.
Throws:
IllegalArgumentException - if URL is null.
See Also:
JAI, ParameterBlockJAI, RenderableOp