Класс 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 с помощью getDefaultReadParam.

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