Package com.pdftools.toolbox.pdf.content

Class ImageMask

java.lang.Object

com.pdftools.toolbox.internal.NativeBase

com.pdftools.toolbox.internal.NativeObject

com.pdftools.toolbox.pdf.content.ImageMask

public class ImageMask
extends NativeObject

Method Summary

Modifier and Type	Method	Description
static ImageMask	create(Document targetDocument, Stream stream)	Create an image mask object from image data.
void	extract(Stream stream)	Extract image mask from PDF
void	extract(Stream stream, ImageType imageType)	Extract image mask from PDF
double	getResolution(AffineTransform transform)	The resolution of an image mask on the page in DPI (dots per inch).
Size	getSize()	The size of the image mask in samples.

Methods inherited from class com.pdftools.toolbox.internal.NativeObject

equals, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static ImageMask create(Document targetDocument,
                               Stream stream)
                        throws java.io.IOException,
                               UnknownFormatException,
                               CorruptException

Create an image mask object from image data.

Supported formats are:

• BMP
• DIB
• JBIG2
• PNG
• GIF

The returned image mask object is not yet painted on any page, but it is associated with the given target document.

Parameters:

targetDocument - the output document with which the returned object is associated

stream - the image data stream

Returns:

the newly created image mask object

Throws:

java.io.IOException - Error reading from the image or writing to the document

UnknownFormatException - The image data has an unknown format or the format is not suitable for an image mask

CorruptException - The image data is corrupt

java.lang.IllegalArgumentException - if the targetDocument argument has already been closed

java.lang.IllegalArgumentException - if the targetDocument argument is read-only

java.lang.IllegalArgumentException - if the stream argument is null

java.lang.IllegalArgumentException - if targetDocument is null

java.lang.IllegalArgumentException - if stream is null

extract

public void extract(Stream stream)
             throws GenericException

Extract image mask from PDF

Facilitate the extraction of image masks from a specified page within a PDF, outputting them in the imageType format.

By default imageType takes the value ImageType.TIFF.

Key considerations include:

• The extraction process isolates the image from the page's resources, neglecting any contextual attributes from the PDF page. Consequently, the original resolution and modifications—such as scaling, rotation, or cropping—that influence the image's appearance on the page are not preserved in the extracted image mask.
• In instances where a GenericException error arises, the output file may be compromised and rendered unusable.

This method is designed to efficiently retrieve image masks without their page-specific modifications, ensuring a straightforward extraction process.

Parameters:

stream - The image mask data stream.

Throws:

java.lang.IllegalArgumentException - if the stream argument is null

java.lang.IllegalStateException - if the image has already been closed

GenericException - if image extraction fails

java.lang.IllegalArgumentException - if stream is null

extract

public void extract(Stream stream,
                    ImageType imageType)
             throws GenericException

Extract image mask from PDF

Facilitate the extraction of image masks from a specified page within a PDF, outputting them in the imageType format.

By default imageType takes the value ImageType.TIFF.

Key considerations include:

• The extraction process isolates the image from the page's resources, neglecting any contextual attributes from the PDF page. Consequently, the original resolution and modifications—such as scaling, rotation, or cropping—that influence the image's appearance on the page are not preserved in the extracted image mask.
• In instances where a GenericException error arises, the output file may be compromised and rendered unusable.

This method is designed to efficiently retrieve image masks without their page-specific modifications, ensuring a straightforward extraction process.

Parameters:

stream - The image mask data stream.

imageType -

Throws:

java.lang.IllegalArgumentException - if the stream argument is null

java.lang.IllegalStateException - if the image has already been closed

GenericException - if image extraction fails

java.lang.IllegalArgumentException - if stream is null

getResolution

public double getResolution(AffineTransform transform)

The resolution of an image mask on the page in DPI (dots per inch).

The resolution is the ratio between the size of the image mask and the size it uses on the page.

Parameters:

transform - The affine transformation matrix of the image mask. Typically, this is the affine transformation matrix of ImageMaskElement.

Returns:

The calculated resolution in DPI.

Throws:

java.lang.IllegalArgumentException - if the transform object has already been closed

java.lang.IllegalArgumentException - if the transform is non-invertible

java.lang.IllegalArgumentException - if transform is null

getSize

public Size getSize()

The size of the image mask in samples. (Getter)

Throws:

java.lang.IllegalStateException - if the image has already been closed