Класс ImageReadParam

java.lang.Object

javax.imageio.IIOParam

javax.imageio.ImageReadParam

Прямые известные подклассы:: JPEGImageReadParam, TIFFImageReadParam

public class ImageReadParam extends IIOParam

Класс, описывающий способ декодирования потока. Экземпляры этого класса или его подклассов используются для передачи предписаний о том, как следует выполнять декодирование, экземплярам ImageReader.

Изображение, закодированное в составе файла или потока, можно представить как протяжённое в нескольких измерениях: пространственных измерениях ширины и высоты, нескольких каналах и нескольких проходах прогрессивного декодирования. Этот класс позволяет выбрать для декодирования непрерывную (гипер)прямоугольную подобласть изображения во всех этих измерениях. Кроме того, пространственные измерения можно субдискретизировать с пропусками. Наконец, можно задать преобразования цвета и формата, управляя ColorModel и SampleModel целевого изображения: для этого можно предоставить BufferedImage или воспользоваться ImageTypeSpecifier.

Объект ImageReadParam используется для задания способа преобразования изображения или набора изображений при чтении из потока в рамках платформы Java Image I/O. Подключаемый модуль для определённого формата изображения возвращает экземпляры ImageReadParam из метода getDefaultReadParam своей реализации ImageReader.

Состояние, поддерживаемое экземпляром ImageReadParam, не зависит от конкретного декодируемого изображения. При фактическом декодировании значения, заданные в параметрах чтения, объединяются с фактическими свойствами изображения, декодируемого из потока, и целевого BufferedImage, в который будут записаны декодированные пиксельные данные. Например, область источника, заданная с помощью setSourceRegion, сначала пересекается с фактической допустимой областью источника. Затем результат смещается на значение, возвращаемое getDestinationOffset, а полученный прямоугольник пересекается с фактической допустимой областью назначения, чтобы определить область назначения, в которую будут записаны данные.

Параметры, заданные с помощью ImageReadParam, применяются к изображению следующим образом. Сначала, если размер визуализации задан методом setSourceRenderSize, всё декодированное изображение визуализируется с размером, указанным в getSourceRenderSize. В противном случае изображение сохраняет естественный размер, заданный ImageReader.getWidth и ImageReader.getHeight.

Затем изображение обрезается по области источника, заданной с помощью getSourceXOffset, getSourceYOffset, getSourceWidth и getSourceHeight.

Затем полученная область подвергается субдискретизации согласно коэффициентам, заданным в IIOParam.setSourceSubsampling. Первый пиксель, количество пикселей в строке и количество строк зависят от параметров субдискретизации. Обозначим минимальные координаты X и Y полученного прямоугольника как (minX, minY), его ширину — как w, а высоту — как h.

Этот прямоугольник смещается на (getDestinationOffset().x, getDestinationOffset().y) и обрезается по границам назначения. Если целевое изображение не задано, считается, что ширина назначения равна getDestinationOffset().x + w, а высота — getDestinationOffset().y + h, чтобы все пиксели области источника можно было записать в назначение.

Пиксели, которые после субдискретизации попадают в целевое изображение и записываются в одном из прогрессивных проходов, заданных с помощью getSourceMinProgressivePass и getSourceNumProgressivePasses, передаются на следующий этап.

Наконец, исходные отсчёты каждого пикселя сопоставляются целевым каналам согласно алгоритму, описанному в комментарии к setDestinationBands.

Разработчики подключаемых модулей могут расширить функциональность ImageReadParam, предоставив подкласс, реализующий дополнительные интерфейсы, специфичные для подключаемого модуля. Подключаемый модуль должен документировать доступные интерфейсы и способы их использования. Средства чтения будут без уведомления игнорировать все расширенные возможности подкласса ImageReadParam, о которых им неизвестно. Кроме того, они могут игнорировать любые необязательные возможности, которые обычно отключают при создании собственных экземпляров ImageReadParam с помощью getDefaultReadParam.

Обратите внимание: если для какой-либо возможности не существует метода проверки, её должны поддерживать все реализации ImageReader (например, размер визуализации источника необязателен, но поддержка субдискретизации обязательна).

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`protected boolean`	`canSetSourceRenderSize`	`true`, если этот `ImageReadParam` позволяет задавать размеры визуализации источника.
`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`	`IIOParamController`, который будет использоваться для предоставления настроек этому объекту `IIOParam` при вызове метода `activateController`.
`protected IIOParamController`	`defaultController`	Объект `IIOParamController` по умолчанию, который будет использоваться для предоставления настроек этому объекту `IIOParam` при вызове метода `activateController`.
`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()`	Возвращает `true`, если это средство чтения позволяет визуализировать исходное изображение с произвольным размером в процессе декодирования с помощью метода `setSourceRenderSize`.
`BufferedImage`	`getDestination()`	Возвращает `BufferedImage`, заданный в данный момент методом `setDestination`, или `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()`	Активирует установленный объект `IIOParamController` для этого объекта `IIOParam` и возвращает полученное значение.
`IIOParamController`	`getController()`	Возвращает текущий установленный объект `IIOParamController`.
`IIOParamController`	`getDefaultController()`	Возвращает объект `IIOParamController` по умолчанию, если он существует, независимо от установленного в данный момент контроллера.
`Point`	`getDestinationOffset()`	Возвращает смещение в целевом изображении, в котором следует разместить пиксели.
`ImageTypeSpecifier`	`getDestinationType()`	Возвращает тип изображения, который будет возвращён при чтении, если он был задан вызовом `setDestination(ImageTypeSpecifier)`, в виде `ImageTypeSpecifier`.
`int[]`	`getSourceBands()`	Возвращает набор используемых каналов источника.
`Rectangle`	`getSourceRegion()`	Возвращает используемую область источника.
`int`	`getSourceXSubsampling()`	Возвращает количество столбцов источника, на которое следует продвигаться для каждого пикселя.
`int`	`getSourceYSubsampling()`	Возвращает количество строк, на которое следует продвигаться для каждого пикселя.
`int`	`getSubsamplingXOffset()`	Возвращает горизонтальное смещение сетки субдискретизации.
`int`	`getSubsamplingYOffset()`	Возвращает вертикальное смещение сетки субдискретизации.
`boolean`	`hasController()`	Возвращает `true`, если для этого объекта `IIOParam` установлен контроллер.
`void`	`setController(IIOParamController controller)`	Задаёт объект `IIOParamController`, используемый для предоставления настроек этому объекту `IIOParam` при вызове метода `activateController`, заменяя любой контроллер по умолчанию.
`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)`	Задаёт децимирующую субдискретизацию, применяемую при вводе-выводе.

Методы, объявленные в классе Object

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()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно посредством вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно посредством вызова notify или interrupt, либо до истечения заданного промежутка времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно посредством вызова notify или interrupt, либо до истечения заданного промежутка времени.

Подробное описание полей

canSetSourceRenderSize

protected boolean canSetSourceRenderSize

true, разрешает ли этот ImageReadParam задавать размеры рендеринга источника. По умолчанию значение равно false. Подклассы должны задавать это значение вручную.

ImageReaders, не поддерживающие настройку размера рендеринга источника, должны задавать этому значению false.

sourceRenderSize

protected Dimension sourceRenderSize

Желаемые ширина и высота рендеринга источника, если canSetSourceRenderSize равно true, или null.

ImageReaders, не поддерживающие настройку размера рендеринга источника, могут игнорировать это значение.

destination

protected BufferedImage destination

Текущий BufferedImage назначения или null, если он не задан. По умолчанию значение равно null.

destinationBands

protected int[] destinationBands

Набор полос назначения, которые будут использоваться, в виде массива ints. По умолчанию значение равно 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 соответствуют одному из ImageTypeSpecifiers, возвращаемых методом getImageTypes объекта ImageReader. Если это не так, средство чтения выбросит IIOException.

Параметры:

destination — BufferedImage, в который будут записываться данные, или null.

См. также:

getDestination

public BufferedImage getDestination()

Возвращает BufferedImage, заданный последним вызовом метода setDestination, или null, если значение не задано.

Возвращает:

BufferedImage, в который будут записываться данные.

См. также:

setDestinationBands

public void setDestinationBands(int[] destinationBands)

Задаёт индексы полос назначения, в которые будут помещены данные. Повторяющиеся индексы не допускаются.

Значение null означает, что будут использоваться все полосы назначения.

Выбор подмножества полос назначения не повлияет на количество полос в выходном изображении при чтении, если изображение назначения не задано: созданное изображение назначения по-прежнему будет иметь столько же полос, сколько имело бы, если бы этот метод не вызывался. Если требуется другое количество полос в изображении назначения, изображение необходимо передать с помощью метода ImageReadParam.setDestination.

Во время чтения или записи средство чтения или записи выбросит IllegalArgumentException, если задано значение больше наибольшего индекса полосы назначения или если количество используемых полос источника и назначения различается. Для автоматической проверки можно использовать метод ImageReader.checkReadParamBandSettings.

Параметры:

destinationBands — массив целочисленных индексов используемых полос.

Выбрасывает:

IllegalArgumentException — если destinationBands содержит отрицательное или повторяющееся значение.

См. также:

getDestinationBands

public int[] getDestinationBands()

Возвращает набор индексов полос, в которые будут помещены данные. Если значение не задано, возвращается null, указывающее, что будут использоваться все полосы назначения.

Возвращает:

индексы используемых полос назначения или null.

См. также:

canSetSourceRenderSize

public boolean canSetSourceRenderSize()

Возвращает true, если это средство чтения позволяет рендерить исходное изображение с произвольным размером в процессе декодирования с помощью метода setSourceRenderSize. Если этот метод возвращает false, вызовы setSourceRenderSize приведут к выбрасыванию UnsupportedOperationException.

Возвращает:

true, если настройка размера рендеринга источника поддерживается.

См. также:

setSourceRenderSize

public void setSourceRenderSize(Dimension size) throws UnsupportedOperationException

Если изображение можно рендерить с произвольным размером, задаёт ширину и высоту источника в соответствии с указанными значениями. Обратите внимание, что значения, возвращаемые методами getWidth и getHeight объекта ImageReader, этим методом не изменяются: они по-прежнему будут возвращать размер изображения по умолчанию. Аналогично, если изображение разбито на тайлы, ширина и высота тайла задаются относительно размера по умолчанию.

Как правило, ширину и высоту следует выбирать так, чтобы их отношение как можно точнее соответствовало соотношению сторон изображения, возвращаемому методом ImageReader.getAspectRatio.

Если этот подключаемый модуль не позволяет задавать размер рендеринга, будет выброшено UnsupportedOperationException.

Чтобы отменить настройку размера рендеринга, передайте значение null для size.

Параметры:

size — Dimension, задающий желаемые ширину и высоту.

Выбрасывает:

IllegalArgumentException — если ширина или высота отрицательна либо равна 0.

UnsupportedOperationException — если этот подключаемый модуль не поддерживает изменение размера изображения.

См. также:

getSourceRenderSize

public Dimension getSourceRenderSize()

Возвращает ширину и высоту исходного изображения, используемые при рендеринге во время декодирования, если они были заданы методом setSourceRenderSize. Значение null указывает, что настройка не выполнялась.

Возвращает:

ширину и высоту рендеринга исходного изображения в виде Dimension.

См. также:

setSourceProgressivePasses

public void setSourceProgressivePasses(int minPass, int numPasses)

Задаёт диапазон прогрессивных проходов, которые будут декодированы. Проходы за пределами этого диапазона игнорируются.

Прогрессивный проход — это повторное кодирование всего изображения, обычно с постепенно повышающимся эффективным разрешением, но требующее большей пропускной способности канала передачи. Чаще всего прогрессивное кодирование используется в формате JPEG, где последующие проходы содержат всё более подробное представление высокочастотных составляющих изображения.

Фактическое количество декодируемых проходов определяется во время декодирования на основе количества проходов, доступных в потоке. Поэтому, если minPass + numPasses - 1 превышает индекс последнего доступного прохода, декодирование завершится на этом проходе.

Значение numPasses, равное Integer.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

public int getSourceMinProgressivePass()

Возвращает индекс первого прогрессивного прохода, который будет декодирован. Если значение не задано, возвращается 0 (что является корректным значением).

Возвращает:

индекс первого декодируемого прохода.

См. также:

getSourceMaxProgressivePass

public int getSourceMaxProgressivePass()

Если getSourceNumProgressivePasses равно Integer.MAX_VALUE, возвращает Integer.MAX_VALUE. В противном случае возвращает

getSourceMinProgressivePass() +
getSourceNumProgressivePasses() - 1

Возвращает:: индекс последнего считываемого прохода или Integer.MAX_VALUE.

getSourceNumProgressivePasses

public int getSourceNumProgressivePasses()

Возвращает количество прогрессивных проходов, которые будут декодированы. Если значение не задано, возвращается Integer.MAX_VALUE (что является корректным значением).

Возвращает:

количество декодируемых проходов.

См. также:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.