Класс ImageReadParam

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

Объект ImageReadParam используется для указания того, как изображение или набор изображений будут преобразованы при вводе из потока в контексте Java Image I/O framework. Плагин для определенного формата изображений вернёт экземпляры 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 (например, размер рендеринга источника необязателен, но субдискретизация должна поддерживаться).