javax.imageio

クラス ImageReadParam

java.lang.Object

javax.imageio.IIOParam

javax.imageio.ImageReadParam

直系の既知のサブクラス:

JPEGImageReadParam

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 です。

クラス javax.imageio.IIOParam から継承されたフィールド

controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, 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	setDestinationType(ImageTypeSpecifier destinationType) ImageTypeSpecifier を使用して、目的のイメージ形式をデスティネーションイメージに設定します。
void	setSourceProgressivePasses(int minPass, int numPasses) 復号化されるプログレッシブパスの範囲を設定します。
void	setSourceRenderSize(Dimension size) イメージを任意のサイズで描画できる場合、ソースの幅と高さを指定された値に設定します。

クラス javax.imageio.IIOParam から継承されたメソッド

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

クラス java.lang.Object から継承されたメソッド

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

フィールドの詳細

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 を構築します。

メソッドの詳細

setDestinationType

public void setDestinationType(ImageTypeSpecifier destinationType)

次のクラスからコピーされた説明: IIOParam

ImageTypeSpecifier を使用して、目的のイメージ形式をデスティネーションイメージに設定します。

読み込み時に、このメソッドを使用してデスティネーションのレイアウトが設定された場合、ImageReader read メソッドの各呼び出しは、指定されたタイプの指示子によって指定された形式を使用して、新しい BufferedImage を返します。副作用として、ImageReadParam.setDestination(BufferedImage) によって設定されるすべてのデスティネーション BufferedImage は、デスティネーションとして設定されなくなります。言い換えると、このメソッドは setDestination((BufferedImage)null) の呼び出しと考えることもできます。

書き込み時に、デスティネーションのタイプはイメージのカラータイプを決めるために使用される場合があります。SampleModel 情報は無視されて、null になります。たとえば、4 バンドのイメージは CMYK または RGBA データのいずれかで表せます。デスティネーションのタイプが設定された場合、その ColorModel はイメージ自体にあるすべての ColorModel をオーバーライドします。これは、イメージの ColorModel が、書き込まれたバンドのサブセットではなくイメージ全体を参照するので、setSourceBands を使用する場合に重要です。

オーバーライド:

setDestinationType、クラス: IIOParam

パラメータ:

destinationType - デスティネーションのレイアウトとカラータイプを決定するために使用する ImageTypeSpecifier。

関連項目:

IIOParam.getDestinationType()

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