Choose a course. Define a graphic.

A graphic request identifies measured course data, selects a hole, green, or complete course subject, and defines the clean artifact that every overlay must match.

Courses

Start with a stable CADDIE.100 course ID.

listCourses returns the licensed course directory available to the current publishable key. Use the stable course ID in every subsequent request instead of relying on a display name.

const courses = await caddie.listCourses();

const raymondMemorial = courses.find(
  (course) => course.name === "Raymond Memorial",
);

Pass an AbortSignal through the optional operation options when course search belongs to a component that may unmount or issue a newer request.

Browser reuse

Reuse verified pixels without weakening overlay authorization.

Publishable-key clients cache immutable image Blobs in IndexedDB for two hours by default. Graphics JS partitions entries with a one-way representation of the key, verifies the artifact SHA-256 on write and read, removes expired or corrupt entries, and bounds storage by age, count, bytes, and least-recently-used access.

The render descriptor and overlay receipt stay in the current tab only and never outlive the server's 30-minute authorization. A same-tab reload can therefore avoid both requests. A new tab or expired receipt makes one descriptor request, then reuses the larger image only when the refreshed artifact key, checksum, dimensions, and content type still match. If they differ, the SDK downloads the replacement before requesting components.

const caddie = createCaddie100Client({
  apiKey: "c100_pk_live_…",
  imageCache: {
    maxAgeMs: 2 * 60 * 60 * 1000,
    maxEntries: 24,
    maxBytes: 100 * 1024 * 1024,
  },
});

// Clear only Graphics JS entries for this API origin.
await caddie.clearImageCache();

// Opt out when the host application requires it.
const uncached = createCaddie100Client({
  apiKey: "c100_pk_live_…",
  imageCache: false,
});

Image bytes onlyThe persistent cache excludes raw API keys, render receipts, overlays, placement instructions, sidecars, coordinates, measurements, and putting data. Storage restrictions or quota failures become ordinary cache misses and never prevent rendering.

Inspect asset.descriptorCacheState and asset.imageCacheState for HIT/MISS diagnostics. Mounted views expose the same values on view.root as data-caddie-descriptor-cache and data-caddie-image-cache.

GraphicRequest

Describe the clean rendered artifact.

const graphicRequest = {
  courseId: "34697689-6423-4c2e-a2c4-b0ecbbfc77d2",
  subject: { type: "hole", holeNumber: 1 },
  output: {
    format: "webp",
    width: 900,
    height: 1500,
    quality: 92,
  },
  style: {
    graphicStyle: "traditional",
    paperTheme: "light",
    fairwayPattern: "medium-stripes",
    teePattern: "plain",
    perimeterTreatment: "classic",
    nearbyHoles: "hidden",
  },
  composition: {
    layout: "portrait",
    flagAnchor: "middle",
    teeAnchor: "middle",
    padding: [0.025, 0.05],
  },
};

Group	Purpose	Common values
courseId	Stable measured-course identity.	UUID from `listCourses`
subject	Selects the spatial subject to compose.	`hole`, `green`, or `course`
output	Defines encoding, dimensions, and quality.	WebP, PNG, JPEG/JPG
style	Selects the graphic style and controls its paper, terrain, turf, context, and perimeter presentation.	`traditional`, plus explicit renderer settings
composition	Fits and orients a hole inside the requested aspect ratio.	Portrait/landscape, anchors, and CSS-style padding
courseComposition	Controls spacing around the automatically rotated full course.	`auto` or CSS-style padding
greenComposition	Controls a green-detail crop, orientation, and placement.	Approach/north, one-to-four meter padding values, rotation, center/auto/edge/corner gravity
greenData	Adds supported green-detail analysis to the clean image.	Green elevation heatmap and break presentation

One exact artifactWidth and height define both the output resolution and composition aspect ratio. The overlay service validates its placements against this render ID, request signature, artifact checksum, and canvas before returning any display pixels.

Delivery methods

Choose the level of browser behavior you need.

// Descriptor only: create the render and receive its artifact contract.
const descriptor = await caddie.createGraphic(graphicRequest);

// Browser asset: authenticate the artifact and create a temporary blob URL.
const asset = await caddie.renderGraphic(graphicRequest);
asset.download("raymond-hole-1.webp");
asset.destroy();

// Interactive view: mount the image and manage optional HTML components.
// The default contain stage preserves the complete artifact in fixed-size hosts.
const view = await caddie.mount(container, graphicRequest, overlays, { fit: "contain" });

createGraphic

Descriptor

Returns the clean image contract and short-lived render receipt without downloading the artifact.

renderGraphic

Asset

Downloads the authenticated image and exposes a blob-backed URL plus download and cleanup methods.

mount

Interactive view

Creates an observed, aspect-ratio-locked stage containing the image and its independently requested overlay layer.

setSmartComponents / addSmartComponent

Components later

Reconciles or appends independently identified instances, including repeated component types, while reusing view-cached placements.

Lifecycle

Cancel stale work and release browser assets.

Pass an AbortSignal to listCourses, createGraphic, renderGraphic, or mount when the calling UI can be replaced.
Use the default contain fit for fixed cards and split panes. Use width when the host grows or scrolls vertically.
Call asset.destroy() for a standalone rendered asset after its blob URL is no longer needed.
Call view.destroy() when an interactive graphic unmounts. It disconnects responsive observation, aborts active overlay work, removes image handlers and DOM, and revokes the asset URL.