Класс ImageReadParam

Изображение, закодированное как часть файла или потока, можно представить как многомерное: пространственные размеры ширины и высоты, количество каналов и количество проходов прогерессивного декодирования. Этот класс позволяет выбрать непрерывную (гипер)прямоугольную подобласть изображения во всех этих измерениях для декодирования. Кроме того, пространственные размеры могут быть выборочно подвыбраны. Наконец, преобразования цвета и формата могут быть заданы путём управления 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, о которых им неизвестно. Они также могут игнорировать любые необязательные функции, которые они обычно отключают при создании собственных экземпляров ImageReadParam через getDefaultReadParam.

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