Working with Pictures

Aspose.Cells FOSS for Java allows you to embed images directly into worksheet cells and retrieve or remove existing pictures. Pictures are managed through the PictureCollection exposed by each Worksheet, and each Picture object provides access to the image data, its anchor position, its detected image type, and its MIME content type.

Overview

Each worksheet exposes its pictures through Worksheet.getPictures(), which returns a PictureCollection. You can add pictures from a byte array, an InputStream, or a file path. The collection provides helper methods for detecting image type from raw bytes, resolving the file extension from image data, and mapping extension to MIME content type.

Accessing Pictures on a Worksheet

Retrieve the PictureCollection via Worksheet.getPictures(). Use PictureCollection.getCount() to determine how many pictures are present. Individual pictures are accessible by zero-based index through PictureCollection.get(index).

Adding a Picture

Three overloads of PictureCollection.add() are available, each returning the zero-based index of the newly added picture:

add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, imageData) from a byte array
add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, stream) from an InputStream
add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, fileName) from a file path

// Embed an image from bytes into cells A1:C5
byte[] imgData = Files.readAllBytes(Paths.get("logo.png"));
int idx = ws.getPictures().add(0, 0, 4, 2, imgData);

Reading Picture Properties

Once you hold a Picture reference, read its anchor position, raw image data, detected image type, and MIME content type:

PictureCollection pics = ws.getPictures();
for (int i = 0; i < pics.getCount(); i++) {
    Picture p = pics.get(i);
    System.out.printf("Name=%s type=%s anchor=[%d,%d]-[%d,%d]%n",
        p.getName(), p.getImageType(),
        p.getUpperLeftRow(), p.getUpperLeftColumn(),
        p.getLowerRightRow(), p.getLowerRightColumn());
}

Detecting Image Type from Raw Bytes

Use PictureCollection.detectImageType(data) to determine the ImageType enum value of a byte array without embedding it first.

PictureCollection pics = ws.getPictures();
byte[] data = Files.readAllBytes(Paths.get("chart.png"));
ImageType type = pics.detectImageType(data);
String ext  = pics.extensionFromData(data);
String mime = pics.contentTypeFromExtension(ext);
System.out.printf("type=%s ext=%s mime=%s%n", type, ext, mime);

Removing a Picture

Use PictureCollection.removeAt(index) to delete a picture by its zero-based index:

ws.getPictures().removeAt(0);

Tips and Best Practices

Use the add(..., imageData) overload when you already have the bytes in memory; use the stream overload to avoid loading large files entirely.
Call PictureCollection.detectImageType(data) to validate the image format before embedding.
Anchor rows and columns are zero-based indices.
Picture.getName() returns an internal identifier, not the original filename.
Pictures are preserved on XLSX round-trip.

Common Issues

Issue	Cause	Fix
`getCount()` returns 0 after add	Stream was closed before add completed	Ensure the InputStream is open and readable
`ImageType.UNKNOWN` returned	Unsupported or corrupt image data	Verify the file is a valid PNG, JPEG, GIF, BMP, or TIFF
Picture position looks wrong	Row/column indices are incorrect	Use zero-based indices for all anchor parameters

FAQ

Which image formats are supported for embedding?

The ImageType enum covers PNG, JPEG, GIF, BMP, TIFF, and EMF. Other formats may embed as binary data but have an ImageType of UNKNOWN.

How do I get the file extension of an embedded picture?

Call PictureCollection.extensionFromData(picture.getData()) with the picture raw bytes.

Can I replace an existing picture image data?

Yes. Retrieve the Picture via get(index) and call setData(bytes).

How do I find a picture by name?

Iterate over all pictures with getCount() and get(index) and compare Picture.getName().

Are pictures preserved when saving to other formats?

Picture preservation depends on the target format. XLSX round-trip is fully supported.

API Reference Summary

Picture

Method	Return type	Description
`getName()`	`String`	Internal name of the picture.
`setName(name)`	`void`	Sets the internal name.
`getUpperLeftRow()`	`int`	Zero-based row of the top-left anchor.
`setUpperLeftRow(row)`	`void`	Sets the top-left anchor row.
`getUpperLeftColumn()`	`int`	Zero-based column of the top-left anchor.
`setUpperLeftColumn(col)`	`void`	Sets the top-left anchor column.
`getLowerRightRow()`	`int`	Zero-based row of the bottom-right anchor.
`setLowerRightRow(row)`	`void`	Sets the bottom-right anchor row.
`getLowerRightColumn()`	`int`	Zero-based column of the bottom-right anchor.
`setLowerRightColumn(col)`	`void`	Sets the bottom-right anchor column.
`getImageType()`	`ImageType`	Detected image format enum value.
`getData()`	`byte[]`	Raw image bytes.
`setData(data)`	`void`	Replaces the raw image bytes.
`getContentType()`	`String`	MIME content type string.

PictureCollection

Method	Return type	Description
`getCount()`	`int`	Number of pictures on the worksheet.
`get(index)`	`Picture`	Returns the picture at the zero-based index.
`add(...)`	`int`	Embeds an image; returns its zero-based index.
`removeAt(index)`	`void`	Removes the picture at the zero-based index.
`detectImageType(data)`	`ImageType`	Detects the image format from raw bytes.
`extensionFromData(data)`	`String`	Returns the file extension for the image data.
`contentTypeFromExtension(ext)`	`String`	Returns the MIME type for a file extension.

Working with Pictures