Module java.desktop
Package javax.imageio

Class IIOParam

java.lang.Object
javax.imageio.IIOParam
直接已知的子类:
ImageReadParam, ImageWriteParam
public abstract class IIOParam extends Object
所有描述流应如何解码或编码的类的超类。此类包含所有由ImageReadParam和ImageWriteParam共享的变量和方法。

此类提供机制来指定源区域和目标区域。在读取时，源是流，内存中的图像是目标。在写入时，这些是相反的。在写入的情况下，只有支持像素替换的写入器才能使用目标区域。

可以为读取器和写入器指定降采样子采样，使用可移动的子采样网格。

可以选择源和目标波段的子集。

  • Field Details

    • sourceRegion

      protected Rectangle sourceRegion
      源区域，如果未设置则为null。

    • sourceXSubsampling

      protected int sourceXSubsampling
      应用于水平方向的降采样子采样。默认情况下，值为1。值不能为负数或0。

    • sourceYSubsampling

      protected int sourceYSubsampling
      应用于垂直方向的降采样子采样。默认情况下，值为1。值不能为负数或0。

    • subsamplingXOffset

      protected int subsamplingXOffset
      在子采样之前应用于子采样网格的水平偏移量。将使用此量从区域的原点或图像的原点（如果未指定区域）偏移此量。

    • subsamplingYOffset

      protected int subsamplingYOffset
      在子采样之前应用于子采样网格的垂直偏移量。将使用此量从区域的原点或图像的原点（如果未指定区域）偏移此量。

    • sourceBands

      protected int[] sourceBands
      一个表示将使用哪些源波段的int数组，或null。如果为null，则要使用的源波段集如setSourceBands方法的注释中所述。不应允许任何值为负数。

    • destinationType

      protected ImageTypeSpecifier destinationType
      用于在读取时生成目标图像或在写入时设置输出颜色类型的ImageTypeSpecifier。如果未设置任何值，则值将为null。默认情况下，值为null。

    • destinationOffset

      protected Point destinationOffset
      将上左解码像素放置在目标中的偏移量。默认情况下，值为（0，0）。

    • defaultController

      protected IIOParamController defaultController
      在调用activateController方法时，将用于为此IIOParam对象提供设置的默认IIOParamController。通常，选择提供自己的默认控制器（通常为GUI）的子类应设置此默认值。
      参见:

    • controller

      protected IIOParamController controller
      在调用activateController方法时，将用于为此IIOParam对象提供设置的IIOParamController。此值将覆盖任何默认控制器，即使为null。
      参见:

  • Constructor Details

    • IIOParam

      protected IIOParam()
      受保护的构造函数只能由子类调用。

  • Method Details

    • setSourceRegion

      public void setSourceRegion(Rectangle sourceRegion)
      设置感兴趣的源区域。感兴趣区域被描述为一个矩形，源图像的左上角像素为（0，0），向下和向右增加值。实际使用的像素数量将取决于setSourceSubsampling设置的子采样因子。如果设置了子采样，使得此数量为零，将抛出IllegalStateException。

      此方法指定的源感兴趣区域将根据需要裁剪以适应实际I/O时的源边界，以及目标偏移、宽度和高度。

      sourceRegion为null将删除任何区域规范，导致使用整个图像。

      参数:
      sourceRegion - 指定源感兴趣区域的Rectangle，或null。
      抛出:
      IllegalArgumentException - 如果sourceRegion为非null，并且sourceRegion.x或sourceRegion.y为负数。
      IllegalArgumentException - 如果sourceRegion为非null，并且sourceRegion.width或sourceRegion.height为负数或0。
      IllegalStateException - 如果子采样使得此区域的子采样宽度或高度为零。
      参见:

    • getSourceRegion

      public Rectangle getSourceRegion()
      返回要使用的源区域。返回值是最近一次调用setSourceRegion设置的值，如果未设置区域，则为null。
      返回:
      感兴趣的源区域作为Rectangle，或null。
      参见:

    • setSourceSubsampling

      public void setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset)
      指定要在I/O上应用的降采样。参数sourceXSubsampling和sourceYSubsampling指定了子采样周期（即，每个源像素后要前进的行数和列数）。具体来说，周期为1将使用每一行或每一列；周期为2将使用每隔一行或一列。参数subsamplingXOffset和subsamplingYOffset指定了第一个子采样像素相对于区域（或图像）原点的偏移量。调整子采样网格的原点对于避免在将非常大的源图像降采样到将被组装成完整降采样图像的目标区域时出现接缝是有用的。大多数用户希望将这些参数简单地保留为0。

      要使用的像素数和扫描线数计算如下。

      扫描线中的子采样像素数由以下公式给出

      truncate[(width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling]。

      如果区域使得宽度为零，则会抛出IllegalStateException。

      如果区域的宽度和高度不是子采样周期的倍数，将子采样网格设置为从源区域原点以外的某个位置开始是有用的。如果子采样网格在每个瓦片之间不保持一致，将在瓦片边界处出现伪影。通过调整每个瓦片的子采样网格偏移量来补偿，可以避免这些伪影。权衡是为了避免这些伪影，瓦片的大小并不相同。在这种情况下要使用的网格偏移量为：
      网格偏移量 = [周期 - （区域偏移模周期）]模周期）

      如果sourceXSubsampling或sourceYSubsampling为0或负数，则会抛出IllegalArgumentException。

      如果subsamplingXOffset或subsamplingYOffset为负数或大于或等于相应的周期，则会抛出IllegalArgumentException。

      没有unsetSourceSubsampling方法；只需调用setSourceSubsampling(1, 1, 0, 0)即可恢复默认值。
      参数:
      sourceXSubsampling - 像素之间要前进的列数。
      sourceYSubsampling - 像素之间要前进的行数。
      subsamplingXOffset - 区域内或图像内第一个子采样的水平偏移量。
      subsamplingYOffset - 区域内或图像内第一个子采样的垂直偏移量。
      抛出:
      IllegalArgumentException - 如果任一周期为负数或0，或者任一网格偏移为负数或大于相应的周期。
      IllegalStateException - 如果源区域使得子采样输出不包含任何像素。

    • getSourceXSubsampling

      public int getSourceXSubsampling()
      返回每个像素要前进的源列数。

      如果未调用setSourceSubsampling，则返回1（这是正确的值）。

      返回:
      源子采样X周期。
      参见:

    • getSourceYSubsampling

      public int getSourceYSubsampling()
      返回每个像素要前进的行数。

      如果未调用setSourceSubsampling，则返回1（这是正确的值）。

      返回:
      源子采样Y周期。
      参见:

    • getSubsamplingXOffset

      public int getSubsamplingXOffset()
      返回子采样网格的水平偏移量。

      如果未调用setSourceSubsampling，则返回0（这是正确的值）。

      返回:
      源子采样网格X偏移量。
      参见:

    • getSubsamplingYOffset

      public int getSubsamplingYOffset()
      返回子采样网格的垂直偏移量。

      如果未调用setSourceSubsampling，则返回0（这是正确的值）。

      返回:
      源子采样网格Y偏移量。
      参见:

    • setSourceBands

      public void setSourceBands(int[] sourceBands)
      设置要使用的源波段的索引。不允许重复索引。

      null值表示将使用所有源波段。

      在读取时，如果指定了大于最大可用源波段索引的值，或者源波段数和要使用的目标波段数不同，读取器或写入器将抛出IllegalArgumentException。可以使用ImageReader.checkReadParamBandSettings方法自动执行此测试。

      从语义上讲，数组将被复制；在此调用之后对数组内容的更改对此 没有影响。

      参数:
      sourceBands - 要使用的整数波段索引数组。
      抛出:
      IllegalArgumentException - 如果sourceBands包含负值或重复值。
      参见:

    • getSourceBands

      public int[] getSourceBands()
      返回要使用的源波段集。返回值是最近一次调用setSourceBands设置的值，如果没有调用setSourceBands，则返回null。

      从语义上讲，返回的数组是一个副本；在此调用之后对数组内容的更改对此 没有影响。

      返回:
      要使用的源波段集，或null。
      参见:

    • setDestinationType

      public void setDestinationType(ImageTypeSpecifier destinationType)
      使用ImageTypeSpecifier设置目标图像的期望图像类型。

      在读取时，如果使用此方法设置了目标的布局，每次调用ImageReader的read方法都将返回一个新的BufferedImage，使用所提供的类型规范指定的格式。作为副作用，通过ImageReadParam.setDestination(BufferedImage)设置的任何目标BufferedImage将不再设置为目标。换句话说，这个方法可以被视为调用setDestination((BufferedImage)null)。

      在写入时，目标类型可能用于确定图像的颜色类型。将忽略SampleModel信息，可能为null。例如，4波段图像可以表示CMYK或RGBA数据。如果设置了目标类型，其ColorModel将覆盖图像本身的任何ColorModel。当使用setSourceBands时，这一点至关重要，因为图像的ColorModel将引用整个图像而不是正在写入的波段子集。

      参数:
      destinationType - 要用于确定目标布局和颜色类型的ImageTypeSpecifier。
      参见:

    • getDestinationType

      public ImageTypeSpecifier getDestinationType()
      返回通过调用setDestination(ImageTypeSpecifier)设置的读取时要返回的图像类型，作为ImageTypeSpecifier。如果没有设置，则返回null。
      返回:
      描述目标类型的ImageTypeSpecifier，或null。
      参见:

    • setDestinationOffset

      public void setDestinationOffset(Point destinationOffset)
      指定在读取时将来的解码像素放置在目标图像中的偏移量，或在写入时将要写入的区域。

      在读取时，要写入目标BufferedImage中的区域将从此偏移开始，并且其宽度和高度由感兴趣的源区域、子采样参数和目标边界确定。

      正常写入不受此方法的影响，只有使用ImageWriter.replacePixels执行的写入受影响。对于这样的写入，指定的偏移量位于正在修改其像素的输出流图像内。

      没有unsetDestinationOffset方法；只需调用setDestinationOffset(new Point(0, 0))即可恢复默认值。

      参数:
      destinationOffset - 作为Point的目标中的偏移量。
      抛出:
      IllegalArgumentException - 如果destinationOffset为null。
      参见:

    • getDestinationOffset

      public Point getDestinationOffset()
      返回要放置像素的目标图像中的偏移量。

      如果尚未调用setDestinationOffsets，则返回一个X和Y值均为零的Point（这是正确的值）。

      返回：
      作为Point的目标偏移量。
      另请参阅：

    • setController

      public void setController(IIOParamController controller)
      设置要在调用activateController方法时为此IIOParam对象提供设置的IIOParamController，覆盖任何默认控制器。如果参数为null，则不会使用任何控制器，包括任何默认控制器。要恢复默认值，请使用setController(getDefaultController())。
      参数：
      controller - 适当的IIOParamController，或null。
      另请参阅：

    • getController

      public IIOParamController getController()
      返回当前安装的任何IIOParamController。如果有默认控制器，则可能是默认控制器，null，或者最近一次调用setController的参数。
      返回：
      当前安装的IIOParamController，或null。
      另请参阅：

    • getDefaultController

      public IIOParamController getDefaultController()
      返回默认的IIOParamController，如果有的话，而不管当前安装的控制器是什么。如果没有默认控制器，则返回null。
      返回：
      默认的IIOParamController，或null。
      另请参阅：

    • hasController

      public boolean hasController()
      如果为此IIOParam对象安装了控制器，则返回true。如果getController不会返回null，则将返回true。
      返回：
      如果安装了控制器，则返回true。
      另请参阅：

    • activateController

      public boolean activateController()
      激活此IIOParam对象的安装的IIOParamController，并返回结果值。当此方法返回true时，此IIOParam对象的所有值将准备好进行下一次读取或写入操作。如果返回false，则此对象中的任何设置都不会被更改（即，用户取消了操作）。

      通常，控制器将是为特定插件的IIOParam子类提供用户界面的GUI。但是，控制器不一定是GUI。

      返回：
      如果控制器正常完成，则返回true。
      抛出：
      IllegalStateException - 如果当前没有安装控制器。
      另请参阅：