Shapes, Images, and Geometry

Shapes live under slide.shapes, slide.layout.shapes, slide.slideMaster.shapes, or group shape collections.

Add shapes

const slide = context.presentation.slides.getItemAt(0);

slide.shapes.addTextBox("Status", {
  left: 60,
  top: 60,
  width: 260,
  height: 48
});

slide.shapes.addGeometricShape(PowerPoint.GeometricShapeType.roundRectangle, {
  left: 60,
  top: 130,
  width: 260,
  height: 90
});

Common geometry APIs cover text boxes, preset geometric shapes, lines, pictures, tables, charts, and groups.

Pictures

Use --input-file to pass local images as data URIs:

witan pptx exec deck.pptx --save --input-file logo=@./logo.png --stdin <<'JS'
return await PowerPoint.run(async context => {
  const slide = context.presentation.slides.getItemAt(0);
  slide.shapes.addPicture(input.logo, {
    left: 54,
    top: 42,
    width: 120,
    height: 60
  });
  await context.sync();
  return true;
});
JS

Witan accepts PNG, JPEG, and SVG image data where the Office.js surface accepts pictures or image fills.

OLE Objects

Witan preserves PowerPoint OLE objects as presentation objects, not as ordinary pictures. Embedded and linked objects keep their payload relationships, fallback images, names, relationship metadata, and slide/layout/master ownership when decks are loaded, saved, duplicated, or imported.

Fallback images are used for rendering when PowerPoint stores a visible image for the OLE object. Some legacy OLE objects use EMF or WMF fallback images; when the renderer cannot decode that image format, Witan preserves the object and payload data and renders a fallback frame instead of dropping the object.

OLE support is preservation-first. Scripts can inspect and manipulate the surrounding shape properties that the PowerPoint object model exposes, but host activation, embedded application automation, and payload replacement are outside the headless runtime.

SmartArt

Witan reads SmartArt as diagram-backed presentation content and uses PowerPoint's persisted drawing cache for rendering when it is available. This lets decks with SmartArt render as their visible shapes, text, connectors, fills, and picture content instead of a generic graphic placeholder.

SmartArt model support includes node text edits, hierarchy edits, seeded layout creation, duplicate/import/delete behavior, and picture-slot replacement for supported list, process, radial, matrix, hierarchy, picture, and 2024 SmartArt layouts.

SmartArt layout behavior is layout-specific. When a semantic edit would make the cached drawing stale, Witan removes the stale cache so PowerPoint can regenerate it on open/save. Decks with missing or unusual SmartArt sidecars are preserved where possible, but unsupported layouts or operations can still require a PowerPoint round trip for full visual regeneration.

Formatting

Shapes expose fill, line, rotation, visibility, alt text, decorative flags, and z-order:

const shape = slide.shapes.getItem("Status Box");
shape.fill.setSolidColor("#E8F2FF");
shape.lineFormat.color = "#1F5DA8";
shape.lineFormat.weight = 1.5;
shape.rotation = 0;
shape.setZOrder(PowerPoint.ShapeZOrder.bringToFront);

Groups

Use addGroup or ShapeScopedCollection.group() to group shapes. Group transforms are reflected in rendering and can be undone with group.ungroup().

SVG conversion

Witan can expose unknown SVG graphic frames through shape.getGraphicOrNullObject() and convert supported SVG graphic content into editable shapes with graphic.convertToShape(). Unsupported SVG features report Office.js-style errors.