Images and Drawings

Witan supports worksheet image authoring through the image APIs, and Witan Render draws supported embedded workbook images and common worksheet shapes.

The public mutation API currently targets embedded raster images. Shape rendering is part of the renderer and verifier surface; shape authoring is not exposed as a standalone xlsx API operation.

Image Model

listImages returns worksheet images:

witan xlsx exec report.xlsx --expr 'await xlsx.listImages(wb, { sheet: "Summary" })'

Each image includes sheet, name, optional sheet-local id, two-cell position anchors, format, dimensions, natural image size, and alternative text fields.

Use getImage to inspect a specific image by name or id:

await xlsx.getImage(wb, "Summary", { name: "Logo" })
await xlsx.getImage(wb, "Summary", { id: 2 })

Add Images

addImage accepts PNG or JPEG image bytes as base64. In CLI scripts, pass local files with --input-file; the script receives a data URI that can be used as the image source.

witan xlsx exec report.xlsx --save --input-file logo=@./logo.png --stdin <<'WITAN'
return await xlsx.addImage(wb, "Summary", {
  name: "Logo",
  source: { base64: input.logo },
  format: "png",
  position: {
    from: { cell: "B2", xOffsetPts: 2, yOffsetPts: 2 },
    to: { cell: "D6" }
  },
  altTextTitle: "Company logo",
  altText: "Logo in the report header",
  preserveAspectRatio: true
})
WITAN

The position uses two anchors. Each anchor has a cell and optional point offsets.

Update And Delete

Use setImage to move, rename, replace bytes, or update alternative text:

await xlsx.setImage(wb, "Summary", { name: "Logo" }, {
  position: {
    from: { cell: "A1" },
    to: { cell: "C4" }
  },
  altText: "Updated report logo"
})

Delete by name or id:

await xlsx.deleteImage(wb, "Summary", { name: "Logo" })

Rendering

Witan Render draws embedded raster images such as PNG, JPEG, BMP, and GIF with z-order, rotation, and flip transforms when those images already exist in the workbook. The image authoring API creates PNG and JPEG images.

Common worksheet shapes, including rectangles, rounded rectangles, ellipses, lines/connectors, triangles, and diamonds, render with fill, border, text, z-order, rotation, and flip transforms. Less common shape geometries can render with a rectangular fallback.

Renderer limits for embedded image bytes and decoded image pixels are documented on Witan Render.

See xlsx API for exact image signatures.