C ABI Contract
eunoia-capi is a thin C ABI seam over the Rust core, meant for hosts whose only interop path is a C ABI—Julia today (via ccall/Libdl), and potentially Go (cgo), C/C++, or Zig. Hosts with a native Rust-binding framework (JavaScript via wasm-bindgen, Python via PyO3, R via extendr) bind the core directly and never touch this surface.
The boundary is deliberately tiny: a diagram spec is an irregular, string-keyed, variable-length payload, so rather than marshal bespoke C structs, every call passes a JSON string and receives a JSON string. There are only five exported symbols. Eunoia.jl is the reference consumer; the Rust source (crates/eunoia-capi/src/lib.rs) is authoritative.
The Contract in One Paragraph
Build a JSON request, hand its NUL-terminated bytes to one of the entry points, and read back a freshly allocated JSON string. Every response is an envelope: branch on the boolean ok. On success the payload fields sit next to "ok": true; on failure you get {"ok": false, "error": "<message>"}. A panic in the core is caught and reported as an error envelope—it never unwinds across the boundary. Every returned pointer is owned by the caller and must be released exactly once with eunoia_free.
Exported Symbols
All eight are extern "C". Strings are NUL-terminated UTF-8.
Symbol | C signature | Returns |
|---|---|---|
|
| fitted Euler layout envelope |
|
| canonical Venn layout envelope |
|
| label/leader placement envelope |
|
| exterior set-label envelope |
|
| glyph placement envelope |
|
| member-label box envelope |
|
| crate version string |
|
| — |
There is no generated C header today—declare the eight prototypes yourself from the table above.
Building the Library
eunoia-capi builds as both a cdylib (for runtime dlopen, as Julia does) and a staticlib:
That writes libeunoia_capi.{so,dylib} (and eunoia_capi.dll on Windows), plus libeunoia_capi.a, into target/release/. The crate compiles with the core's parallel feature on, so the restart loop is rayon-parallel inside each call.
eunoia_euler
Fits an area-proportional Euler diagram from set sizes and returns a layout.
Request:
Field | Type | Default | Meaning |
|---|---|---|---|
| array of | (required) | Sizes keyed by combination string ( |
| string |
|
|
| string |
|
|
| number | — | Area outside every set; fits a bounding container. See Complement. |
| integer | — | RNG seed for reproducible fits. |
| integer | core default | Raise the set-count ceiling (clamped core-side). |
All remaining fields are optional fitting and plotting knobs; omitting one keeps the core default. The enum-valued knobs are snake_case strings, validated up front (a bad token errors regardless of the other inputs):
Field | Type | Valid tokens/notes |
|---|---|---|
| string |
|
| number | Smoothing |
| string |
|
| string |
|
| string |
|
| integer | Random restarts of the two-phase fit; lowest loss kept. |
| number | Loss above which the CMA-ES escape kicks in. |
| integer | Per-optimizer iteration cap. |
| number | Convergence tolerances. |
| integer | Parallel restart job count. |
| integer | Vertices per polygonized shape/region (default |
| number | Pole-of-inaccessibility anchor precision (default |
| number | Sliver-rejection fraction (default |
These mirror the Rust Fitter/PlotOptions; the defaults are what you want unless you are deliberately exploring. See the Fitter pipeline chapter for what they do.
The default optimizer for shapes with analytic gradients is cmaes_bounded_lm, which uses bounded Levenberg-Marquardt for its retry and polishing stages. The old tokens trf and cmaes_trf remain accepted as deprecated synonyms for bounded_levenberg_marquardt and cmaes_bounded_lm, respectively.
For final-layout unbounded LM stages, tolerance sets the relative model-reduction threshold (default 1e-3), and ftol overrides it. The test checks both actual and predicted reduction. xtol bounds the relative attempted step (default 1e-6), and gtol bounds residual/Jacobian-column orthogonality (default 1e-8). Zero disables the corresponding LM test. Bounded LM uses gtol as an absolute scaled-gradient threshold instead; it ignores xtol and ftol. L-BFGS uses tolerance for its absolute gradient-norm and cost-change tests. All four values must be finite and nonnegative; invalid values return an error.
Success response (abridged):
shapesis a tagged union ontype. Per shape the geometry fields vary:circlehasradius;ellipsehassemi_major/semi_minor/rotation;squarehasside;rectanglehaswidth/height;rotated_rectangleaddsrotation. Every variant carrieslabeland alabel_anchorpoint.metricsmaps are keyed by combination string (always exclusive form). See Goodness of Fit.plot_datacarries renderable geometry: every coordinate is an[x, y]pair, region keys are combination strings, set keys are set names.set_anchor_regionspairs a set's label with the region it anchored to (by key, so renderers needn't compare floats); sets that fell back to the whole-shape pole are omitted.container({x, y, width, height}) is present only when the request setcomplement.
eunoia_venn
Lays out a canonical n-set Venn diagram—a fixed template, not proportional (sizes are ignored, every intersection is drawn).
Field | Type | Default | Meaning |
|---|---|---|---|
| array of string | (required) | Set names, in order; their count selects the arrangement. |
| string |
| Same shape tokens as |
| number | — | Frames the diagram with a bounding container (surfaced as |
The response is the same LayoutOut envelope as eunoia_euler. Circles, squares, and axis-aligned rectangles support up to three sets; rotated rectangles support up to four, and ellipses support up to five.
eunoia_place_labels
Resolves one collision-aware label position (and leader-line geometry where needed) per region, given the region polygons and caller-measured label box sizes. This usually means a render → measure → re-place loop; see Label placement.
Field | Type | Notes |
|---|---|---|
|
| Region pieces; |
|
| Measured label box sizes, in diagram units. |
|
| Optional bounding frame. |
| object | Optional; omitted fields keep core defaults (see below). |
The strategy knobs: leader.type is "straight" (default) or "elbow"; leader.placement is "raycast" (default), "force_directed", or "matched" for straight leaders (ignored for elbow); leader.margin/iterations/min_gap tune those; precision is the pole-of-inaccessibility precision; tether is "poi" (default) or "boundary"; leader_gap is the gap from label to leader.
All three straight strategies refine their exit directions to reduce the leader's distance through other exclusive regions, including regions without labels. They preserve label clearance and matched angular order. Enclosed sources can require some traversal; elbow placement uses separate routing.
Only regions present in both regions and sizes get a placement. The success payload is a placements map:
kind is interior, exterior_raycast, exterior_force_directed, exterior_elbow, exterior_matched, or unknown (forward-compat). tether, leader_end, and leader_waypoints appear only for exterior placements that need a leader line.
eunoia_place_set_labels
Resolves one label position per set, sitting just outside that set's own shape with no leader line. The sibling of eunoia_place_labels: keyed by set name rather than region, and it needs the shape outlines (plot_data.shape_outlines) rather than the region pieces, because what it hugs is the set's own silhouette. See Label placement.
For nested sets, the sweep favors keeping the inner label inside the enclosing outline, clear of its boundary, while still outside its own shape. Shape clearance remains best-effort when space is tight or the collision guard moves a label.
Field | Type | Notes |
|---|---|---|
|
| Closed ring per set — |
|
| Measured label box sizes, in diagram units. |
|
| Optional; labels that fit inside it are preferred. |
| object | Optional; omitted fields keep core defaults. |
The strategy knobs: margin is the gap between the outline and the label box (default half the label height); angular_steps is the number of candidate angles swept around each shape (default 180, clamped up to 8); obstacles is a list of {x, y, width, height} keep-out boxes — pass the measured region-label boxes so set names avoid the quantities; precision is the pole-of-inaccessibility precision.
Only sets present in both outlines and sizes get a placement. The success payload is a placements map keyed by set name:
kind is always exterior_set, and there is no leader geometry: the label is adjacent to the shape it names, so there is nothing to connect.
eunoia_place_glyphs
Set options.boundary_gap to control clearance to region edges, holes, and label obstacles independently of gap. Centers keep a distance of at least radius * (1 + boundary_gap) from these boundaries, while the minimum center-to-center distance remains 2 * radius * (1 + gap). Omitting boundary_gap uses gap, preserving the default behavior.
Packs equally-sized circular glyphs—one mark per data unit, eulerGlyphs-style—inside each region, given the region polygons and a per-region count. See Glyphs.
Field | Type | Notes |
|---|---|---|
|
| Region pieces; |
|
| Glyphs to place per region; zero or missing skips the region. |
| object | Optional; omitted fields keep core defaults (see below). |
The options knobs: arrangement is "uniform" (default, hex lattice spread across the region), "rectangular" (aligned rows and columns with equal spacing), "low_discrepancy" (deterministic Halton candidates filtered by spacing and boundary clearance), or "random" (seeded dart throwing); radius fixes the glyph radius (omit for the auto mode, which picks the largest radius at which every region holds its full count); gap is extra breathing room as a fraction of the radius (default 0.25), applied both between glyphs (minimum center-to-center distance 2r * (1 + gap)) and against the region boundary (centers keep clearance r * (1 + gap) to every ring); seed (default 0) and max_attempts (default 300) only affect "random"; precision (default 0.01) tunes the pole-of-inaccessibility search; obstacles is an array of keep-out boxes {"x", "y", "width", "height"} (center plus full extents, like container on eunoia_place_labels) that glyph centers clear by r * (1 + gap)—usually the caller's measured label boxes, since labels are drawn over glyphs. Degenerate boxes are ignored rather than rejected. obstacle_policy is "best_effort" (default, permits overlap when glyphs do not fit) or "strict" (requires clearance and reports overflow in unplaced). Both preserve the automatic radius floor of half the radius chosen without obstacles; see Glyphs.
Only regions present in both regions and counts, with a positive count, get glyphs. The success payload carries the diagram-wide radius and the center points:
unplaced maps each overflowing region to the count that did not fit. It can be present in either sizing mode, including when strict obstacles block placement at the automatic radius floor.
eunoia_place_glyph_boxes
Packs per-item text boxes—member names—inside each region, given the region polygons and the width × height you measured for every item. The rectangular-footprint sibling of eunoia_place_glyphs. See Member labels.
Field | Type | Notes |
|---|---|---|
|
| Region pieces, exactly as for |
|
| One measured box per item, in the order you want them placed. |
| object | Optional; omitted fields keep core defaults (see below). |
The options knobs: arrangement is "uniform" (default, row/shelf packing— rows of one shared height, boxes left to right at their own widths, the block centered on the region's pole of inaccessibility) or "random" (seeded rectangular dart throwing); scale fixes the diagram-wide box factor (omit for the auto mode); min_scale (default 0.35) is the lower end of the auto bracket; gap (default 0.25) is breathing room as a fraction of the row height, not of a radius; seed, max_attempts, precision, obstacles, and obstacle_policy behave exactly as in eunoia_place_glyphs. Strict obstacles preserve both min_scale and the floor of half the obstacle-free scale; items that still do not fit are reported in unplaced. The returned boxes remain a prefix of the input.
Set target_aspect_ratio to a positive width-to-height ratio to balance uniform rows. For example, "target_aspect_ratio": 1.0 favors a roughly square occupied block, including its halo. The packer maximizes the placed prefix before preferring the closest candidate ratio, keeping boundary, hole, and obstacle clearance. This preference does not change automatic scale selection. Omit it to keep the first complete packing. Non-positive values disable it, and "random" ignores it.
The success payload carries the diagram-wide scale and one [cx, cy, w, h] quad—center plus full extents—per placed item:
boxes[combo] is always a prefix of sizes[combo], so boxes[combo][i] belongs to item i—render your text at fontSize * scale. Auto-scale only ever shrinks (the bracket tops out at 1.0), since the caller owns the reference font size. Text boxes are much wider than tall, so unplaced is far more common here than for the disc packer; see Member labels for what to do about it.
eunoia_version and eunoia_free
eunoia_version() takes no input and returns the crate version (e.g. "1.10.2") as a string you must free. eunoia_free(ptr) releases any string returned by this library; passing NULL is a no-op.
Combination Keying
A combination string is a single set name ("A") or an intersection joined by & with no spaces ("A&B", "A&B&C"). Sizes and metrics are in exclusive form (the piece belonging to exactly those sets) unless you set input_type: "inclusive" on the request. Output maps are emitted in sorted key order, so serialization is deterministic.
Memory Ownership
Every char * returned by eunoia_euler, eunoia_venn, eunoia_place_labels, eunoia_place_set_labels, eunoia_place_glyphs, eunoia_place_glyph_boxes, and eunoia_version is heap-allocated by Rust and owned by the caller. Hand it back to eunoia_free exactly once. Do not free it with the host's free(), do not free it twice, and do not read it after freeing—each is undefined behavior. Passing NULL to eunoia_free is safe.
Errors
Failures come back as {"ok": false, "error": "<message>"}—a valid envelope, so you parse it the same way and branch on ok. The error string is hand-escaped so the error path can never itself fail to serialize. Representative messages:
null input pointer: the input pointer wasNULL.input is not valid UTF-8: …: the bytes weren't UTF-8.invalid JSON: …: the input didn't parse.invalid optimizer 'x' (want …): an enum token was unrecognized.failed to build spec: …orfailed to fit diagram: …: the core rejected the spec or the fit failed.panic in eunoia core: a panic was caught at the boundary.
Thread-Safety
The entry points are pure and stateless: each call is self-contained, holds no shared state, and exposes no synchronization primitives across the boundary. You may call them concurrently from multiple threads. The only parallelism is the rayon restart loop inside a single eunoia_euler call—it does not leak out.
Worked Example (C)
A minimal round-trip: declare the prototypes, fit, print, free. Link against the built library.
extern char *;
extern void ;
int
LD_LIBRARY_PATH=target/release
