モジュール java.desktop
パッケージ javax.imageio

クラスImageReadParam

java.lang.Object
javax.imageio.IIOParam
javax.imageio.ImageReadParam
直系の既知のサブクラス:
JPEGImageReadParam, TIFFImageReadParam
public class ImageReadParam extends IIOParam
ストリームが復号化される方法を記述するクラスです。 このクラスまたはサブクラスのインスタンスは、ImageReaderのインスタンスへ規定の「方法」についての情報を提供するために使用されます。

ファイルまたはストリームの一部として符号化されたイメージは、空間的な寸法の幅と高さ、バンド数、およびプログレッシブ・デコーディング・パスの数など、複数の次元に拡大して考えられます。 このクラスは、これらのすべての次元で、連続的なイメージの(ハイパー)矩形サブ領域を使用して、復号化の選択を可能にします。 さらに、空間的な寸法は非連続的に間引きできます。 最後に、色および形式の変換は、BufferedImageを提供するか、ImageTypeSpecifierを使用することにより、デスティネーション・イメージのColorModelとSampleModelを制御して指定されます。

ImageReadParamオブジェクトは、Java Image I/Oフレームワークのコンテキストで、イメージまたはイメージのセットをストリームから入力に変換する方法を指定するために使用します。 特定のイメージ形式のプラグインは、ImageReader実装のgetDefaultReadParamメソッドからImageReadParamのインスタンスを返します。

ImageReadParamのインスタンスによって管理される状態は、復号化される特定のイメージから独立しています。 実際に復号化が行われる場合、読込みパラメータに設定された値は、ストリームから復号化中のイメージの実際のプロパティおよび復号化されたピクセル・データを受け取るデスティネーションBufferedImageに結合されます。 たとえば、setSourceRegionを使用して設定されたソース領域は、実際の有効なソース領域に最初に交差します。 結果は、getDestinationOffsetで返される値によって変換され、実際の有効なデスティネーション領域に交差する結果の矩形が、書き込まれるデスティネーション領域になります。

ImageReadParamによって指定されたパラメータは、次のようにイメージに適用されます。 最初に、描画のサイズがsetSourceRenderSizeによって設定されている場合、復号化されるイメージ全体はgetSourceRenderSizeにより指定されたサイズで描画されます。 それ以外の場合、イメージはImageReader.getWidthおよびImageReader.getHeightによって指定された実際のサイズで描画されます。

次に、イメージはgetSourceXOffset、getSourceYOffset、getSourceWidth、およびgetSourceHeightによって指定されたソース領域にクリップされます。

結果の領域は、IIOParam.setSourceSubsamplingによって指定された係数によって間引きされます。 最初のピクセル、行あたりピクセル数、および行数は、すべてサブサンプリング設定に依存します。 幅w、高さhの結果の矩形の最小X座標とY座標(minX、minY)を呼び出します。

この矩形は、(getDestinationOffset().x、getDestinationOffset().y)にオフセットされ、デスティネーション境界にクリップされます。 デスティネーション・イメージが設定されていない場合、デスティネーションは、ソース領域のすべてのピクセルをデスティネーションに書込みできるように、幅getDestinationOffset().x+w、高さgetDestinationOffset().y+hに定義されます。

サブサンプリング後に、デスティネーション・イメージ内に配置され、getSourceMinProgressivePassとgetSourceNumProgressivePassesによって指定されるプログレッシブ・パスの1つに書き込まれるピクセルは、次のステップに渡されます。

最後に、各ピクセルのソース・サンプルはsetDestinationBandsのコメントに記述されるアルゴリズムを使用して、デスティネーション・バンドにマッピングされます。

プラグインの書込み側は、プラグイン固有の追加のインタフェースを実装するサブクラスを提供することにより、ImageReadParamの機能を拡張できます。 どのインタフェースが利用可能か、それがどのように使用されるかは、プラグインによります。 読取り側は、認識しないImageReadParamサブクラスの拡張機能をそのまま無視します。 また、getDefaultReadParamを介して、読取り側自体のImageReadParamインスタンスを作成する場合、通常、使用不可であるオプション機能はすべて無視されます。

クエリー・メソッドは、将来のために用意されている場合を除き、ImageReaderのすべての実装でサポートされる必要があります。たとえば、ソースの描画サイズはオプションですが、サブサンプリングはサポートされる必要があります。

関連項目:
ImageReader, ImageWriter, ImageWriteParam

  • フィールド詳細

    • canSetSourceRenderSize

      protected boolean canSetSourceRenderSize
      このImageReadParamがソースの描画寸法を設定できる場合はtrueです。 デフォルト値はfalseです。 サブクラスは手動でこの値を設定する必要があります。

      ソースの描画サイズの設定をサポートしないImageReaderは、この値をfalseに設定する必要があります。

    • sourceRenderSize

      protected Dimension sourceRenderSize
      canSetSourceRenderSizeがtrueの場合、目的のソース描画の幅と高さです。それ以外の場合はnullです。

      ソースの描画サイズの設定をサポートしないImageReaderは、この値を無視します。

    • 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を提供します。 現在設定されているイメージは、read、readAll、およびreadRasterメソッドによって書き込まれ、これに対する参照はこれらのメソッドによって返されます。

      上述のメソッドからのピクセル・データは、getDestinationOffsetによって指定される座標の開始時に書き込まれます。

      destinationがnullの場合、新しく作成されたBufferedImageは、これらのメソッドによって返されます。

      読込み時に、イメージのColorModelとSampleModelが、ImageReaderのgetImageTypesメソッドから返されるImageTypeSpecifierの1つに対応することを確認するために検査されます。 対応しない場合、読取り側はIIOExceptionをスローします。

      パラメータ:
      destination - 書き込まれるBufferedImage、またはnull。
      関連項目:
      getDestination()

    • getDestination

      public BufferedImage getDestination()
      setDestinationメソッドによって現在設定されているBufferedImageを返します。何も設定されていない場合はnullを返します。
      戻り値:
      書き込まれるBufferedImage。
      関連項目:
      setDestination(java.awt.image.BufferedImage)

    • 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()
      データが配置されているバンド・インデックスのセットを返します。 値が設定されていない場合、すべてのデスティネーション・バンドが使用されていることを示す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
      イメージを任意のサイズでレンダリングできる場合、ソースの幅と高さを指定された値に設定します。 ImageReaderのgetWidthおよびgetHeightメソッドから返される値は、このメソッドによって影響を受けないことに注意してください。これらは、引き続きイメージのデフォルトのサイズを返します。 同様に、イメージがタイリングされる場合も、タイルの幅と高さはデフォルトのサイズによって指定されます。

      通常、幅と高さは、幅と高さの比率がImageReader.getAspectRatioから返されるイメージの縦横比と正確に近似するよう選択する必要があります。

      このプラグインで描画サイズの設定ができない場合、UnsupportedOperationExceptionがスローされます。

      描画サイズの設定を削除するには、sizeに値nullを渡します。

      パラメータ:
      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が使用可能な最後のパスのインデックスより大きい場合、復号化はそのパスで終了します。

      Integer.MAX_VALUEのnumPassesの値は、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()

    • getSourceMinProgressivePass

      public int getSourceMinProgressivePass()
      復号化される最初のプログレッシブ・パスのインデックスを返します。 値が設定されていない場合、正しい値0が返されます。
      戻り値:
      復号化される最初のパスのインデックス。
      関連項目:
      setSourceProgressivePasses(int, int), getSourceNumProgressivePasses()

    • getSourceMaxProgressivePass

      public int getSourceMaxProgressivePass()
      getSourceNumProgressivePassesがInteger.MAX_VALUEと等しい場合は、Integer.MAX_VALUEを返します。 それ以外の場合はgetSourceMinProgressivePass()+getSourceNumProgressivePasses() - 1を返します。
      戻り値:
      読み取られる最後のパスのインデックス、またはInteger.MAX_VALUE。

    • getSourceNumProgressivePasses

      public int getSourceNumProgressivePasses()
      復号化されるプログレッシブ・パスの数を返します。 値が設定されていない場合、正しい値Integer.MAX_VALUEが返されます。
      戻り値:
      復号化されるパスの数。
      関連項目:
      setSourceProgressivePasses(int, int), getSourceMinProgressivePass()