模块  java.desktop
软件包  javax.imageio

Class ImageReadParam

  • 已知直接子类:
    JPEGImageReadParamTIFFImageReadParam

    public class ImageReadParam
    extends IIOParam
    描述如何解码流的类。 此类或其子类的实例用于向ImageReader实例提供规定性的“操作方法”信息。

    编码为文件或流的一部分的图像可以被认为是在多个维度上延伸:宽度和高度的空间维度,多个频带以及多个渐进解码通道。 该类允许选择所有这些维度中的图像的连续(超)矩形子区域用于解码。 另外,可以不连续地对空间维度进行二次采样。 最后,可以通过控制目标图像的ColorModelSampleModel来指定颜色和格式转换,方法是提供BufferedImage或使用ImageTypeSpecifier

    ImageReadParam对象用于指定如何在Java Image I / O框架的上下文中从流的输入转换图像或一组图像。 特定图像格式的ImageReadParam将从其ImageReader实现的getDefaultReadParam方法返回ImageReadParam实例。

    ImageReadParam的实例维护的状态独立于正被解码的任何特定图像。 当进行实际解码时,在读取参数中设置的值与从流和将接收解码像素数据的目的地BufferedImage解码的图像的实际属性组合。 例如,使用setSourceRegion设置的源区域将首先与实际有效源区域相交。 结果将由getDestinationOffset返回的值getDestinationOffset ,生成的矩形与实际有效目标区域相交,以生成将要写入的目标区域。

    ImageReadParam指定的参数应用于图像,如下所示。 首先,如果渲染大小已由setSourceRenderSize设置,则整个解码图像getSourceRenderSize给出的大小呈现。 否则,图像的自然尺寸由ImageReader.getWidthImageReader.getHeight

    接下来,图像被裁剪针对由指定的源区getSourceXOffsetgetSourceYOffsetgetSourceWidth ,和getSourceHeight

    然后根据IIOParam.setSourceSubsampling给出的因子对得到的区域进行二次采样。 第一个像素,每行像素数和行数都取决于子采样设置。 呼叫的最小X和所得矩形(Y坐标minXminY ),其宽度w和其高度h

    该矩形是通过(偏移getDestinationOffset().xgetDestinationOffset().y )和针对目的地边界裁剪。 如果未设置目标图像,则目标定义为宽度为getDestinationOffset().x + w ,高度为getDestinationOffset().y + h以便可以将源区域的所有像素写入目标。

    在子采样之后,在目标图像内着陆的像素以及由getSourceMinProgressivePassgetSourceNumProgressivePasses指定的渐进通道之一写入的getSourceNumProgressivePasses被传递到下一步骤。

    最后,根据setDestinationBands的注释中描述的算法将每个像素的源样本映射到目标频带。

    插件编写者可以通过提供实现附加的插件特定接口的子类来扩展ImageReadParam的功能。 由插件来记录哪些接口可用以及如何使用它们。 读者将默默地忽略他们不知道的ImageReadParam子类的任何扩展功能。 此外,他们可能会忽略通过getDefaultReadParam创建自己的ImageReadParam实例时通常禁用的任何可选功能。

    请注意,除非存在功能的查询方法,否则它必须得到所有ImageReader实现的支持( 例如,源渲染大小是可选的,但必须支持子采样)。

    另请参见:
    ImageReaderImageWriterImageWriteParam
    • 字段详细信息

      • canSetSourceRenderSize

        protected boolean canSetSourceRenderSize
        true如果此ImageReadParam允许设置源渲染维度。 默认情况下,该值为false 子类必须手动设置此值。

        ImageReader s不支持设置源渲染大小应将此值设置为false

      • sourceRenderSize

        protected Dimension sourceRenderSize
        如果canSetSourceRenderSizetruenull ,则所需的渲染宽度和源高度。

        ImageReader s不支持设置源渲染大小可能会忽略此值。

      • destination

        protected BufferedImage destination
        当前目的地BufferedImage ,如果没有设置, null 默认情况下,该值为null
      • destinationBands

        protected int[] destinationBands
        要使用的目标波段集,作为int的数组。 默认情况下,该值为null ,表示应按顺序写入所有目标波段。
      • minProgressivePass

        protected int minProgressivePass
        从源读取的渐进传递的最小索引。 默认情况下,该值设置为0,表示应该解码从第一个可用传递开始的传递。

        子类应确保此值为非负值。

      • numProgressivePasses

        protected int numProgressivePasses
        从源读取的最大渐进传递数。 默认情况下,该值设置为Integer.MAX_VALUE ,表示应解码最后一次可用传递的传递。

        子类应确保此值为正。 此外,如果该值不是Integer.MAX_VALUE ,则minProgressivePass + numProgressivePasses - 1不应超过Integer.MAX_VALUE

    • 构造方法详细信息

      • ImageReadParam

        public ImageReadParam()
        构造一个 ImageReadParam
    • 方法详细信息

      • setDestination

        public void setDestination​(BufferedImage destination)
        提供BufferedImage作为解码像素数据的目标。 当前设置的图像将被写入到readreadAll ,并readRaster方法,以及对它的引用将由这些方法返回。

        来自上述方法的像素数据将从getDestinationOffset指定的偏移处开始写入。

        如果destinationnull ,那么这些方法将返回新创建的BufferedImage

        在读出时,该图像被检查以验证其ColorModelSampleModel对应之一ImageTypeSpecifier ■从返回ImageReadergetImageTypes方法。 如果没有,读者将抛出IIOException

        参数
        destination - 要写入的BufferedImage,或 null
        另请参见:
        getDestination()
      • setDestinationBands

        public void setDestinationBands​(int[] destinationBands)
        设置将放置数据的目标波段的索引。 不允许重复索引。

        null表示将使用所有目标频段。

        如果没有指定目标图像,则选择目标频带子集不会影响读取的输出图像中的频带数量; 创建的目标图像仍将具有相同数量的波段,就好像从未调用此方法一样。 如果需要目标图像中的不同数量的波段,则必须使用ImageReadParam.setDestination方法提供图像。

        在读取或写入时,如果指定了大于最大目标频带索引的值,或者要使用的源频带和目标频带的数量不同,则读取器或写入器将抛出IllegalArgumentException ImageReader.checkReadParamBandSettings方法可用于自动化该测试。

        参数
        destinationBands - 要使用的整数带索引数组。
        异常
        IllegalArgumentException - 如果 destinationBands包含负数或重复值。
        另请参见:
        getDestinationBands()IIOParam.getSourceBands()ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)
      • getDestinationBands

        public int[] getDestinationBands()
        返回将放置数据的band索引集。 如果未设置任何值,则返回null以指示将使用所有目标频段。
        结果
        要使用的目标频段的索引,或 null
        另请参见:
        setDestinationBands(int[])
      • canSetSourceRenderSize

        public boolean canSetSourceRenderSize()
        如果此读取器允许通过setSourceRenderSize方法将源图像作为解码过程的一部分以任意大小呈现,则返回true 如果此方法返回false ,则调用setSourceRenderSize将抛出UnsupportedOperationException
        结果
        true如果支持设置源渲染大小。
        另请参见:
        setSourceRenderSize(java.awt.Dimension)
      • setSourceRenderSize

        public void setSourceRenderSize​(Dimension size)
                                 throws UnsupportedOperationException
        如果图像能够以任意大小渲染,请将源宽度和高度设置为提供的值。 请注意, getWidthgetHeight方法返回的值ImageReader不受此方法的影响; 他们将继续返回图像的默认大小。 类似地,如果图像也是平铺的,则根据默认大小给出平铺宽度和高度。

        通常,应选择宽度和高度,使得宽度与高度的比率接近于图像的纵横比,如ImageReader.getAspectRatio所返回。

        如果此插件不允许设置渲染大小,则将抛出UnsupportedOperationException

        要删除渲染大小设置, nullsize传递值size

        参数
        size - Dimension表示所需的宽度和高度。
        异常
        IllegalArgumentException - 如果宽度或高度为负或0。
        UnsupportedOperationException - 如果此插件不支持图像大小调整。
        另请参见:
        getSourceRenderSize()ImageReader.getWidth(int)ImageReader.getHeight(int)ImageReader.getAspectRatio(int)
      • getSourceRenderSize

        public Dimension getSourceRenderSize()
        返回源图像的宽度和高度,因为它们将在解码过程中呈现,如果它们是通过setSourceRenderSize方法设置的。 null表示未进行任何设置。
        结果
        渲染的源图像宽度和高度为 Dimension
        另请参见:
        setSourceRenderSize(java.awt.Dimension)
      • setSourceProgressivePasses

        public void setSourceProgressivePasses​(int minPass,
                                               int numPasses)
        设置要解码的渐进传球的范围。 超出此范围的通行证将被忽略。

        逐行传递是整个图像的重新编码,通常是逐渐更高的有效分辨率,但需要更大的传输带宽。 渐进编码的最常见用途是以JPEG格式找到,其中连续传递包括高频图像内容的更详细表示。

        基于流中可用的实际通过的数量,在解码期间确定要解码的实际通过次数。 因此,如果minPass + numPasses - 1大于最后可用传递的索引,则解码将以该传递结束。

        numPassesInteger.MAX_VALUE表示应该读取所有从minPass转发的传球。 否则,最后一次通过的指数( minPass + numPasses - 1 )不得超过Integer.MAX_VALUE

        没有unsetSourceProgressivePasses方法; 通过致电setSourceProgressivePasses(0, Integer.MAX_VALUE)可以获得相同的效果。

        参数
        minPass - 要解码的第一个传递的索引。
        numPasses - 要解码的最大传递次数。
        异常
        IllegalArgumentException - 如果 minPass为负数, numPasses为负数或0,或者 numPasses小于 Integer.MAX_VALUE但是 minPass + numPasses - 1大于 INTEGER.MAX_VALUE
        另请参见:
        getSourceMinProgressivePass()getSourceMaxProgressivePass()
      • getSourceMaxProgressivePass

        public int getSourceMaxProgressivePass()
        如果getSourceNumProgressivePasses等于Integer.MAX_VALUE ,则返回Integer.MAX_VALUE 否则,返回getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1
        结果
        要读取的最后一个传递的索引,或 Integer.MAX_VALUE