Класс ImageReadParam

java.lang.Object
- javax.imageio.IIOParam
- - javax.imageio.ImageReadParam

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

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 (например, размер рендеринга источника необязателен, но субдискретизация должна поддерживаться).

См. также:: ImageReader, ImageWriter, ImageWriteParam

Поля

Модификатор и тип	Поле и описание
`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`.

Поля, унаследованные от класса javax.imageio.IIOParam

controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, 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`	`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

true это поле ImageReadParam разрешает установить размеры рендеринга источника. По умолчанию значение равно 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, используя формат, указанный в предоставленном спецификаторе типа. В качестве побочного эффекта, любое назначение BufferedImage установленное методом ImageReadParam.setDestination(BufferedImage) больше не будет установлено как назначение. Другими словами, этот метод можно рассматривать как вызов setDestination((BufferedImage)null).

При записи, тип назначения может использоваться для определения цветового типа изображения. Информация SampleModel будет проигнорирована и может быть null. Например, изображение с 4 полосами может представлять данные CMYK или RGBA. Если тип назначения задан, его ColorModel перекроет любые ColorModel самого изображения. Это имеет решающее значение при использовании setSourceBands, так как ColorModel изображения будет относиться ко всему изображению, а не к подмножеству полос, которые записываются.

Переопределяет:: setDestinationType в классе IIOParam
Параметры:: destinationType - ImageTypeSpecifier, используемый для определения макета и цветового типа назначения.
См. также:: IIOParam.getDestinationType()

setDestination

public void setDestination(BufferedImage destination)

Предоставляет BufferedImage для использования в качестве назначения для декодированных пиксельных данных. Текущее установленное изображение будет записываться методами read, readAll, и readRaster, а ссылка на него будет возвращена этими методами.

Данные пикселей из упомянутых методов будут записываться, начиная со смещения, указанного в getDestinationOffset.

Если destination равно null, методами будет возвращено вновь созданное BufferedImage.

Во время чтения изображение проверяется, чтобы убедиться, что его ColorModel и SampleModel соответствуют одному из ImageTypeSpecifier возвращаемых методом ImageReader's getImageTypes метода. В противном случае, читатель выбросит IIOException.

Параметры:: destination - BufferedImage, в который будет выполняться запись, или null.
См. также:: getDestination()

getDestination

public BufferedImage getDestination()

Возвращает BufferedImage, текуще заданное методом setDestination, или 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()

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

Возвращает:: true если установка размера рендеринга источника поддерживается.
См. также:: setSourceRenderSize(java.awt.Dimension)

setSourceRenderSize

public void setSourceRenderSize(Dimension size)
                         throws UnsupportedOperationException

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

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

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

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

Параметры:: 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 больше, чем индекс последнего доступного прохода, декодирование завершится на этом проходе.

Значение 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(), 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()

© 1993, 2020, 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.