Golf Course
Graphics.

Golf graphics rendering overview

One configurable graphics engine.

Pass a CADDIE.100 golf course ID. The API loads measured golf course geometry and runs the same tested Canvas implementation as the interactive golf map renderer—same geometry parsing, visual styles, composition controls, export function, and projection object.

The private employee Graphics Generator submits this same structured POST /api/v1/courses/{courseId}/graphics/images contract for hole, green, and course subjects. The previous /maps/images path remains available as a compatibility alias. The preview is the same encoded file an API client downloads rather than a separate browser approximation.

The requested width and height define both output resolution and the composition aspect ratio. The renderer computes fitting, rotation, placement, and the spatial transform on a normalized canvas with that ratio, then scales uniformly to the requested pixels. It does not crop or stretch the completed map.

Golf graphics endpoints

Generate finished imagery directly.

Graphics use the product-specific subresource /courses/{courseId}/graphics/images. The legacy /maps/images alias remains callable for existing integrations while new clients get a route that is unambiguous beside Maps tile and static-image delivery.

Every image and overlay request requires an organization API credential with the course-graphics:read scope. Send it through x-api-key or Authorization: Bearer …; never place a private c100_live_… or c100_test_… key in browser code or a URL. Browser requests require a c100_pk_… publishable key with a separately licensed browser scope and exact allowed origin.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images/hole-1/webp?graphicStyle=traditional&width=1440&height=2400&paperTheme=%23DDE7D2&context=none&flagAnchor=right&teeAnchor=left&padding=.025,.05,0,.05" \
  -H "x-api-key: YOUR_API_KEY" \
  --output hole-1.webp

curl -X POST https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "subject": { "type": "hole", "holeNumber": 1 },
    "output": { "format": "webp", "width": 1440, "height": 2400 },
    "style": {
      "graphicStyle": "traditional",
      "paperTheme": "#DDE7D2",
      "context": { "graphing": false, "edges": false, "contours": false, "washes": false }
    },
    "composition": {
      "mode": "preset",
      "flagAnchor": "right",
      "teeAnchor": "left",
      "padding": ".025 .05 0 .05"
    }
  }'

Separate browser project

Graphics JS now has dedicated documentation.

The HTTP API remains documented on this page. Installation, initialization, course and graphic requests, and every interactive overlay component now live in a separate Graphics JS documentation section designed to grow with the SDK.

Graphic style registry

One course scene, distinct visual languages.

traditional is the stable default: a filled, colored illustration with terrain modeling, material treatments, mowing patterns, and detailed surroundings. pencil is a preview style that interprets the same measured geometry as restrained graphite linework. colored-pencil is a second preview treatment that adds uniform soft flat colors and restrained path geometry without inheriting Traditional's terrain, materials, textures, or detail layers. All three support hole, green, and full-course subjects, while each renderer declares the semantic data it needs and receives a separate request and cache identity.

Pencil hazards and tree crowns use the selected paper color as an underlay before their graphite outlines and marks are drawn. Overlapping trees therefore remain legible, and a bunker or water polygon can cleanly cover an underlying course-boundary line. Overture water is reconciled with course-authored water in the shared semantic pipeline before Pencil renders the combined water geometry.

Pencil does not load elevation or putting-surface detail and does not render paths, buildings, transportation segments, land-surface detail, infrastructure, green heatmaps, or slope arrows. It fixes terrain intensity at 0.5, disables terrain texture, uses blank fairways and plain tees, and requires housing=none and overtureSegments=none. Explicit incompatible controls are rejected instead of being silently ignored; context.contours and context.washes must also remain false.

Colored Pencil keeps those same no-terrain and no-putting-surface constraints. It fills every member of a feature class with the same soft color, retains the simple tree, bunker-dot, and water-wave marks, restores course-authored cart paths, and defaults overtureSegments to small. Its data gate narrows that Overture transportation to service, pedestrian, footway, steps, path, track, cycleway, and bridleway classes while also admitting building footprints and parking polygons. Polygonal paths and parking share one light-gray fill without outlines; linear paths use one light-gray stroke without a darker casing; buildings use a slightly darker gray fill without an outline. None receives roof geometry, concrete lighting, highlights, shadows, terrain response, or texture. Set overtureSegments=none to omit only Overture paths; buildings and parking remain independent. all is rejected.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images/hole-1/webp?graphicStyle=pencil&width=1440&height=2400&paperTheme=light&context=edges" \
  -H "x-api-key: YOUR_API_KEY" \
  --output hole-1-pencil.webp

curl "https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images/hole-1/webp?graphicStyle=colored-pencil&width=1440&height=2400&paperTheme=light&context=edges&overtureSegments=small" \
  -H "x-api-key: YOUR_API_KEY" \
  --output hole-1-colored-pencil.webp

curl -X POST https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "subject": { "type": "green", "holeNumber": 9 },
    "output": { "format": "webp", "width": 1200, "height": 1200 },
    "style": {
      "graphicStyle": "pencil",
      "paperTheme": "light",
      "context": { "graphing": false, "edges": true, "contours": false, "washes": false }
    },
    "greenComposition": {
      "orientation": "approach",
      "paddingMeters": "8 12 18 12",
      "rotationDegrees": 0,
      "gravity": "center"
    }
  }'

Inspect the live style registry and data requirements ↗

Style controls

The complete renderer palette.

graphicStyle=traditional identifies the established filled, colored, terrain-modeled treatment. graphicStyle=pencil draws the same measured course geometry and composition as warm-paper graphite linework. graphicStyle=colored-pencil adds soft flat feature colors and restrained paths while remaining terrain-, texture-, and detail-free. Traditional remains the default, and each style receives a separate normalized request and cache identity. See Graphic styles for each preview style's semantic data gate and fixed controls.

paperTheme accepts the Light, Dark, and Transparent presets or a strict six-digit hex value. Transparent removes the paper fill, graphing grid, and paper grain while retaining any selected edges, contours, or washes. WebP and PNG preserve alpha; JPEG composites transparent pixels over pure white because it has no alpha channel. Use context=none when the output should contain only map artwork. Green details and other edge-to-edge compositions can still be fully opaque because rendered terrain fills their complete viewport. The interactive generator exposes Light, Dark, and Transparent.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images/hole-1/webp?width=1440&height=2400&paperTheme=transparent&context=edges" \
  -H "x-api-key: YOUR_API_KEY" \
  --output hole-1-transparent.webp

greenery=auto coordinates the context base, generated rough, fairway and first cut, greens, tee boxes, three-foot fringes, grass terrain flecks, forest floor, and tree crowns using a state-level proxy for the GCSAA agronomic regions. classic preserves the exact established colors and is the fallback for unknown and non-US locations. Cool blue, cool apple, warm emerald, and warm golden form a restrained cool-to-warm ramp—not claims about a course's exact cultivar. Some region boundaries split states, and season, overseeding, nutrition, irrigation, and mowing direction can change turf appearance, so use an explicit family when local information is known.

terrainTexture=true is the default and adds the scale-aware, material-specific fleck pass to base turf, generated rough, maintained grass, bunker sand, and concrete. Set terrainTexture=false to omit only those added flecks; the established drawRough grain, mowing patterns, surface fills, and measured terrain lighting remain intact. A subtly lighter green context surface is the permanent fallback below course terrain. Overture desert, sand, beach, barren, heath, scree, bare-rock, rock, and stone surfaces can cover it; shrub and grass land-cover polygons remain intentionally ignored because the fallback already supplies dependable green ground. Mountain-range, plateau, volcano, caldera-rim, wetland, ridge, and cliff landforms blend above those physical materials without erasing them. Wetlands use a slightly translucent shared mask with layered warm olive and yellow-green tones between the forest floor and permanent base, with dense olive-green marsh vegetation, rare small green-led brown accents, and sparse transparent deep-blue or brown-green moisture speckles; authoritative rivers, streams, lakes, and ponds remain above it. Polygon features become masked fills, ridge-like lines become narrow accents, and point rock or stone features become individual top-down faceted rocks without inventing unsupported filled areas. A universal generated rough envelope is then placed above the landforms around fairways, greens, tees, and selected bunkers. Surface water does not generate green rough. The envelope’s broad noisy distance-field transition extends outside the requested buffers, preserving solid rough near each included feature while eliminating a traced outer line. Forest floor sits above the generated rough, and maintained features remain above both. Measured canopy crowns remain authoritative, while a capped deterministic pass places occasional witness crowns only in large empty gaps inside forest polygons—including narrow strips—so mapped woodland never reads as dark rough. Desert and barren use the same tan, brown, and gray mineral aggregate with sparse scale-aware dry vegetation; barren has no separate mosaic or color treatment. waterTreatment=auto uses the course state: southern coastal states plus California and Hawaii select Light, northern states select Dark, and every remaining state selects Medium. Tropical US territories select Light; unknown and non-US locations use Medium. Water remains visible for every supported treatment. housing=auto uses the course state’s modal IECC climate zone by county count: zones 1–3 select warm brown, clay, sand, and brick roofs; zone 4 selects a mixed warm and cool palette; and zones 5–8 select cool gray, slate, and charcoal roofs. Cross-family ties, unknown states, and non-US courses fall back to mixed. housing=none removes housing roofs and footprint edges. Housing roofs and height-scaled ground shadows share the terrain light source, fade with the course perimeter, and omit unrecognizable edge slivers. Adjacent thin parallel roof sections share one ridge instead of receiving duplicate peaks. Every valid polygonal Overture water class and every valid surface linear-water class is accepted without a class allowlist and unioned with measured course water before shoreline smoothing. Pools, underground or covered waterways, and non-drawable point labels are excluded. Overture parking polygons reuse the concrete segment material and measured terrain response. Fountain points render as clipped top-down mist and ripples only when they fall inside rendered water. On hole renders with edges enabled, admitted Overture segment centerlines and housing footprint polygons continue outside the terrain without procedural gables unless housing is none. Green and full-course renders support graphing context only. The former texture and contextTexture names remain supported as deprecated aliases.

For Traditional, overtureSegments=all preserves every normalized transportation segment. small keeps only known road classes at residential scale or below—residential and living streets, unclassified and service roads, pedestrian ways, footways, steps, paths, tracks, cycleways, and bridleways—while excluding larger roads, rail, water routes, and unknown classes. none removes both segment concrete and its paper-edge continuation. Pencil always uses none and omits course-authored paths, buildings, land surfaces, and infrastructure. Colored Pencil restores course-authored cart paths and accepts small or none; its server-side data gate further narrows small to service and non-motorized path classes while independently admitting Overture building footprints and parking polygons. Other land surfaces and infrastructure remain excluded. Overture water remains enabled for both Pencil styles and is reconciled with course-authored water in the shared semantic pipeline.

perimeterTreatment applies to hole and full-course images. classic is the default. On a full course, every hole's Classic shapes are drawn into one shared source-over mask, so overlapping buffers combine naturally while separate hole groups stay separate; the renderer does not add a hull or fill gaps. This produces the organic buffered course design even when the authored course envelope contains rectangular sections. legacy-v1 preserves the authored measured hole or course envelope—including those rectangular source sections—while none renders the projected viewport edge-to-edge. Classic applies a 21.6-yard buffer to the measured center line, 25 yards to the tee-box polygon furthest from the green, 20 yards to all shorter tee boxes, 25 yards to fairway polygons, and 25 yards to the green polygon. It adds a 23-yard circle wherever the line crosses a fairway or green boundary. From the center of the furthest tee-box polygon, it intersects the measured centerline at true radial distances and proposes landing circles of 60 yards at 350 yards, 60 at 300, 60 at 250, 50 at 200, 40 at 150, and 35 at 100 yards. Forward candidates less than 150 yards from the green center are omitted. A reverse schedule centered on the green adds a 45-yard circle at a true radial distance of 150 yards and a 40-yard circle at 100 yards; either is omitted when the measured line does not reach that distance. classic-wide, classic-wider, and classic-widest increase only those forward and reverse landing-circle buffers by 10%, 20%, and 30% from the base values. When the corresponding furthest tee record provides authored dogleg.coordinates, the Classic union also adds a 50-yard circle at that point; no dogleg is inferred when the field is absent. Every Classic render uses a 20-yard physical feather, and the canonical full-course fit uses the combined outer support extent. Retired default and tapered-family inputs remain accepted as compatibility aliases.

nearbyHoles independently controls maintained surfaces from other holes that enter the selected hole’s viewport. hidden is the default and preserves a clean single-hole illustration. stroked-dark and stroked-light add measured outlines at 15% opacity in dark green or white. filled-dark and filled-light fill those measured surfaces using the same colors and opacity. The legacy stroked value remains an alias for stroked-dark. detailed renders those surfaces with the selected colors, mowing patterns, textures, and terrain response. Nearby-hole artwork is always clipped by perimeterTreatment.

Composition presets contain the complete measured hole envelope within configurable composition.padding, defaulting to 5% on every side. Padding follows CSS shorthand order: one value applies everywhere; two apply vertical/horizontal; three apply top/horizontal/bottom; and four apply top/right/bottom/left. Unitless values above 0 and below 1 are image fractions, while values 1 or greater are output pixels; explicit % and px strings are also accepted. In Portrait, top/bottom padding set the flag/tee endpoint bands while Left/Middle/Right remain 25%/50%/75% horizontal presets. In Landscape, left/right padding set the endpoint bands while Top/Middle/Bottom remain 25%/50%/75% vertical presets. Set composition.mode to exact for direct percentage targets. Full-course courseComposition.padding uses the same shorthand after automatic rotation; omit it or use auto to preserve the canonical course fit.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images/course/webp?width=2400&height=1600&padding=.03,.05,.07,.04" \
  -H "x-api-key: YOUR_API_KEY" \
  --output course.webp

Values through 2.2 use the standard terrain response. Above 2.2, the complete terrain contribution scales proportionally; for example, 4.4 is twice the contribution of 2.2. Before that gain is applied, terrain cells and smoothing filters adapt to the geographic camera scale across hole, green, and course subjects. Close crops therefore retain coherent landforms instead of magnifying sub-meter sampling noise. The late terrain pass carries measured lighting through the context base, every Overture surface material and blended landform, generated rough, forest floor, fairways and their first cut, greens, tees, fringes, bunker sand, and Overture concrete paths. Sand and concrete responses are deliberately restrained so bunker details and path surfaces remain legible; concrete relief is clipped to each class-derived physical path corridor.

Fairway stripes and tee stripes are defined in real-world meters and converted through the resolved camera projection, so they retain mowing-scale proportions across hole, green, and course views. Large, Medium, and Small checked fairways cross two perpendicular mowing passes to form diamonds, using the same 7.2-meter, 3.8-meter, and 2-meter band widths as their stripe counterparts. The legacy checkered-v1 and checkered-v2 inputs remain accepted as aliases for medium-checks and small-checks. Maintained edges use the same physical model: fairway first cut is six feet, while green and tee fringe are three feet.

View live capability response ↗

Green detail composition

Frame the green and its approach.

Use the green-N subject to create a close rendering of a specific hole's measured green. Green images default to 1200 × 1200 pixels, greenOrientation=approach, greenGravity=center, and 12 meters of padding around the complete green polygon. greenPaddingMeters accepts one to four meter values in the same CSS shorthand order for asymmetric spacing. The viewport is filled with rendered rough and course features from edge to edge—there is no paper border or blurred perimeter.

In the interactive generator, select Green, choose the hole, and use the Square, Portrait, or Landscape buttons as convenient dimension presets. These are playground presets rather than an API enum: width and height remain fully custom, while greenGravity controls placement independently of aspect ratio.

The renderer fits the complete green as large as possible while retaining at least the requested metric padding. Center gravity aligns the measured green center to the image center at every aspect ratio, keeping center-origin overlays aligned across a multi-green layout. Top, right, bottom, left, and corner gravities pin the padded green to those output edges. Auto preserves the earlier shape-based placement: square centers padded bounds, portrait pins them to the top, and landscape pins them to the right. Approach orientation is resolved from a point interpolated 100 yards back along the complete incoming play line. Landscape still rotates the approach-oriented projection clockwise, and all rotation is applied in the projection so terrain, tree crowns, and linework remain sharp.

Add heatmap=elevation to show terrain that is meaningfully low in transparent blue and meaningfully high in transparent red. The renderer smooths sub-putt noise and requires meaningful signed relief as grade over putting-scale distances before applying color. Sustained modeled slope and regional structure can strengthen an established high or low area, but cannot independently turn a near-median ripple into a red/blue pair. It does not force a fixed percentage of the green to be colored, so a genuinely flat green can remain mostly transparent while a shelf, basin, false front, or broad tilt remains visible.

The same elevation layer is available on hole-N images. It is clipped to that hole's measured green while the tees, fairway, hazards, trees, and surrounding hole composition remain unchanged. The interactive generator exposes the Heatmap control for both Hole and Green subjects. Fall-line marks remain exclusive to the close green-detail subject.

The service loads the requested hole from the server-side putting-surface-v1 bundle, which provides one-yard source elevations with a 20-meter exterior buffer, a two-foot slope grid, and gradients sampled across six feet. Exterior samples support smoothing through the boundary, but only cells inside the measured green determine normalization and statistics. The finished heatmap is clipped to the exact green polygon, filling the putting surface without a transparent feathered edge.

The heatmap communicates regional high and low terrain rather than predicting one particular putt; green speed, putt direction, grain, moisture, and wind are not inputs to this elevation layer.

Slope arrows default to breakStyle=fluid, breakDensity=medium, and breakColor=dark. Set breakStyle=grid for an evenly spaced, collision-free staggered field of traditional straight arrows with shorter, heavier shafts and triangular heads. Keep breakStyle=fluid for the organic curved treatment seeded from higher to lower elevation. Fluid marks integrate the changing downhill bearing into a streamline, vary their spacing deterministically, and consolidate nearby downstream paths. Full-path clearance stops a converging mark before it touches an existing arrow; stricter minimum lengths and curvature checks remove cramped collision remnants while preserving valid edge-clipped marks.

Use breakDensity=light|medium|high to trade visual calm for additional terrain detail; mark budgets scale with measured green area, while safety bounds and collision checks protect unusually tiny or large greens. High density shortens and slightly thins each mark as spacing tightens, but does not increase the resolution of the source terrain model. Set breakColor=dark|light|#RRGGBB for a preset or custom color. In a URL, percent-encode the leading hash as %23. Every arrow shaft and head renders at solid opacity; modeled slope affects only length and stroke width.

The arrows describe terrain direction, not a predicted ball path. They do not account for green speed, mowing grain, moisture, wind, or ball physics. A slope-magnitude heatmap is reserved for a later presentation.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images/hole-9/webp?width=1440&height=2400&terrainIntensity=3.6&heatmap=elevation&heatmapOpacity=0.42" \
  -H "x-api-key: YOUR_API_KEY" \
  --output hole-9-elevation.webp

curl "https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images/green-9/webp?width=1200&height=1200&greenOrientation=approach&greenPaddingMeters=8,12,18,12&greenGravity=center&terrainIntensity=3.6&heatmap=elevation&heatmapOpacity=0.42&breaks=true&breakStyle=fluid&breakDensity=high&breakColor=dark" \
  -H "x-api-key: YOUR_API_KEY" \
  --output green-9.webp

curl -X POST https://caddie100.com/api/v1/courses/COURSE_ID/graphics/images \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "subject": { "type": "green", "holeNumber": 9 },
    "output": { "format": "webp", "width": 900, "height": 1400 },
    "style": { "terrainIntensity": 3.6, "context": "none" },
    "greenComposition": {
      "orientation": "approach",
      "paddingMeters": "8 12 18 12",
      "rotationDegrees": 0,
      "gravity": "center"
    },
    "greenData": {
      "heatmap": "elevation",
      "heatmapOpacity": 0.42,
      "breaks": true,
      "breakStyle": "fluid",
      "breakDensity": "high",
      "breakColor": "#24594B"
    }
  }'

Golf graphics output

Image formats and limits.

WebP is the default output for structured API requests and the internal Graphics Generator. Use webp in direct image URLs, or explicitly select PNG or JPEG/JPG. WebP and PNG preserve transparent backgrounds; JPEG composites them over white. Width and height may be 320–8,000 pixels, with a maximum area of 32 megapixels. Portrait holes default to 1440 × 2400, landscape holes to 2400 × 1440, green details to 1200 × 1200, and courses to 2400 × 1600. WebP and JPEG quality is 40–95; terrain intensity is 0.5–5.0.