クラス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

フィールドのサマリー

フィールド

修飾子と型	フィールド	説明
protected boolean	canSetSourceRenderSize	このImageReadParamがソースの描画寸法を設定できる場合はtrueです。
protected BufferedImage	destination	現在のデスティネーションBufferedImage、または何も設定されていない場合はnullです。
protected int[]	destinationBands	intの配列としての、使用するデスティネーション・バンドのセットです。
protected int	minProgressivePass	ソースから読み取るプログレッシブ・パスの最小インデックスです。
protected int	numProgressivePasses	ソースから読み取るプログレッシブ・パスの最大数です。
protected Dimension	sourceRenderSize	canSetSourceRenderSizeがtrueの場合、目的のソース描画の幅と高さです。それ以外の場合はnullです。

クラスで宣言されたフィールド IIOParam

controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, subsamplingYOffset

修飾子と型	フィールド	説明
protected IIOParamController	controller	activateControllerメソッドが呼び出されたときに、このIIOParamオブジェクトの設定を指定するために使用するIIOParamControllerです。
protected IIOParamController	defaultController	activateControllerメソッドが呼び出されたときに、このIIOParamオブジェクトの設定を指定するために使用するデフォルトのIIOParamControllerです。
protected Point	destinationOffset	左上隅のデコードされたピクセルが配置されるデスティネーションのオフセットです。
protected ImageTypeSpecifier	destinationType	読込み時にデスティネーションのイメージを生成する、または書込み時に出力のカラー・タイプを設定するために使用するImageTypeSpecifierです。
protected int[]	sourceBands	使用するソース・バンドを示すint配列、またはnullです。
protected Rectangle	sourceRegion	ソース領域、または何も設定されない場合はnullとなります。
protected int	sourceXSubsampling	水平方向に適用される間引きサブサンプリングです。
protected int	sourceYSubsampling	垂直方向に適用される間引きサブサンプリングです。
protected int	subsamplingXOffset	サブサンプリングする前にサブサンプリング・グリッドに適用される水平方向のオフセットです。
protected int	subsamplingYOffset	サブサンプリングする前にサブサンプリング・グリッドに適用される垂直方向のオフセットです。

コンストラクタのサマリー

コンストラクタ

コンストラクタ	説明
ImageReadParam()	ImageReadParamを構築します。

メソッドのサマリー

修飾子と型	メソッド	説明
boolean	canSetSourceRenderSize()	この読取り側が、復号化プロセスの一部として、setSourceRenderSizeメソッドによって、ソース・イメージを任意のサイズで描画できるようにする場合、trueを返します。
BufferedImage	getDestination()	setDestinationメソッドによって現在設定されているBufferedImageを返します。何も設定されていない場合はnullを返します。
int[]	getDestinationBands()	データが配置されているバンド・インデックスのセットを返します。
int	getSourceMaxProgressivePass()	getSourceNumProgressivePassesがInteger.MAX_VALUEと等しい場合は、Integer.MAX_VALUEを返します。
int	getSourceMinProgressivePass()	復号化される最初のプログレッシブ・パスのインデックスを返します。
int	getSourceNumProgressivePasses()	復号化されるプログレッシブ・パスの数を返します。
Dimension	getSourceRenderSize()	setSourceRenderSizeメソッドによって設定されている場合、復号化の間に描画されるように、イメージの幅と高さを返します。
void	setDestination(BufferedImage destination)	復号化されるピクセル・データのデスティネーションとして使用するBufferedImageを提供します。
void	setDestinationBands(int[] destinationBands)	データが配置されているデスティネーション・バンドのインデックスを設定します。
void	setSourceProgressivePasses(int minPass, int numPasses)	復号化されるプログレッシブ・パスの範囲を設定します。
void	setSourceRenderSize(Dimension size)	イメージを任意のサイズでレンダリングできる場合、ソースの幅と高さを指定された値に設定します。

クラスで宣言されたメソッド IIOParam

activateController, getController, getDefaultController, getDestinationOffset, getDestinationType, getSourceBands, getSourceRegion, getSourceXSubsampling, getSourceYSubsampling, getSubsamplingXOffset, getSubsamplingYOffset, hasController, setController, setDestinationOffset, setDestinationType, setSourceBands, setSourceRegion, setSourceSubsampling

修飾子と型	メソッド	説明
boolean	activateController()	このIIOParamオブジェクトに対してインストールされているIIOParamControllerをアクティブにし、結果の値を返します。
IIOParamController	getController()	現在インストールされているIIOParamControllerを返します。
IIOParamController	getDefaultController()	デフォルトのIIOParamControllerがある場合は、現在インストールされているコントローラとは関係なく、これを返します。
Point	getDestinationOffset()	ピクセルが配置されるデスティネーション・イメージのオフセットを返します。
ImageTypeSpecifier	getDestinationType()	ImageTypeSpecifierとして、setDestination(ImageTypeSpecifier)の呼出しによって設定された場合、読込みによって返されるイメージのタイプを返します。
int[]	getSourceBands()	使用するソース・バンドのセットを返します。
Rectangle	getSourceRegion()	使用するソース領域を返します。
int	getSourceXSubsampling()	ピクセルごとに浮き出るソース列の数を返します。
int	getSourceYSubsampling()	ピクセルごとに浮き出るソース行の数を返します。
int	getSubsamplingXOffset()	サブサンプリング・グリッドの水平方向のオフセットを返します。
int	getSubsamplingYOffset()	サブサンプリング・グリッドの垂直方向のオフセットを返します。
boolean	hasController()	このIIOParamオブジェクトにインストールされたコントローラがある場合はtrueを返します。
void	setController(IIOParamController controller)	activateControllerメソッドを呼び出して、すべてのデフォルト・コントローラをオーバーライドするときに、このIIOParamオブジェクトの設定を指定するために使用するIIOParamControllerを設定します。
void	setDestinationOffset(Point destinationOffset)	読込み時の場合は、将来デコードされるピクセルが配置されるオフセット、書込み時の場合は、領域が書き込まれるオフセットをデスティネーション・イメージに指定します。
void	setDestinationType(ImageTypeSpecifier destinationType)	ImageTypeSpecifierを使用して、目的のイメージ形式をデスティネーション・イメージに設定します。
void	setSourceBands(int[] sourceBands)	使用するソース・バンドのインデックスを設定します。
void	setSourceRegion(Rectangle sourceRegion)	処理対象のソース領域を設定します。
void	setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset)	間引きサブサンプリングを指定して入出力に適用します。

クラスオブジェクトで宣言されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

修飾子と型	メソッド	説明
protected Object	clone()	このオブジェクトのコピーを作成して、返します。
boolean	equals(Object obj)	このオブジェクトと他のオブジェクトが等しいかどうかを示します。
protected void	finalize()	削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。 最終決定は非推奨であり、将来のリリースで削除される可能性があります。
final Class<?>	getClass()	このObjectの実行時クラスを返します。
int	hashCode()	このオブジェクトに対するハッシュ・コード値を返します。
final void	notify()	このオブジェクトのモニターで待機中のスレッドを1つ再開します。
final void	notifyAll()	このオブジェクトのモニターで待機中のすべてのスレッドを再開します。
String	toString()	オブジェクトの文字列表現を返します。
final void	wait()	現在のスレッドが目覚めるまで待機します。通常、notifiedまたはinterruptedです。
final void	wait(long timeoutMillis)	現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。
final void	wait(long timeoutMillis, int nanos)	現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

フィールド詳細

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(BufferedImage)

setDestinationBands

public void setDestinationBands(int[] destinationBands)

データが配置されているデスティネーション・バンドのインデックスを設定します。 インデックスの複製は使用できません。

値nullは、すべてのデスティネーション・バンドが使用されることを示します。

デスティネーション・バンドが指定されない場合、デスティネーション・バンドのサブセットの選択は、読込みの出力イメージのバンド数に影響を与えません。作成されるデスティネーション・イメージは、このメソッドが呼び出されなかったかのように、同じバンド数を保持します。 デスティネーション・イメージに異なるバンド数が必要な場合、ImageReadParam.setDestinationメソッドを使用してイメージを提供する必要があります。

デスティネーション・バンドの最大インデックスより大きい値が指定された場合、または使用するソース・バンドの数とデスティネーション・バンドの数が異なる場合、読み込みまたは書込み時に、読取り側または書込み側によってIllegalArgumentExceptionがスローされます。 ImageReader.checkReadParamBandSettingsメソッドは、このテストを自動化するために使用されます。

パラメータ:

destinationBands - 使用する整数型バンド・インデックスの配列。

スロー:

IllegalArgumentException - destinationBandsが負または重複する値を保持する場合。

関連項目:

• getDestinationBands()
• IIOParam.getSourceBands()
• ImageReader.checkReadParamBandSettings(ImageReadParam, int, int)

getDestinationBands

public int[] getDestinationBands()

データが配置されているバンド・インデックスのセットを返します。 値が設定されていない場合、すべてのデスティネーション・バンドが使用されていることを示すnullが返されます。

戻り値:

使用するデスティネーション・バンドのインデックス、またはnull。

関連項目:

• setDestinationBands(int[])

canSetSourceRenderSize

public boolean canSetSourceRenderSize()

この読取り側が、復号化プロセスの一部として、setSourceRenderSizeメソッドによって、ソース・イメージを任意のサイズで描画できるようにする場合、trueを返します。 このメソッドがfalseを返す場合、setSourceRenderSizeの呼出しはUnsupportedOperationExceptionをスローします。

戻り値:

ソース描画サイズの設定をサポートする場合はtrue。

関連項目:

• setSourceRenderSize(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(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()