Analysis and reports
How GCS calculates section properties — the two-path client/server model, Preview vs Calculated badges, error codes, and generating Full or Summary PDF reports.
Overview
Section properties update automatically as you draw and edit the section geometry. There is no Run or Calculate button — the analyser reacts to every change within a short debounce delay. Two separate computation paths produce the same numbers from the same inputs; the badge in the Section Properties panel tells you which path’s results are currently displayed.
:::note[Derived reads require a saved section — September 2026 (#5842)]
The section-properties derived read and the mesh derived read are now gated on the section being saved. Requesting computed properties or a mesh on an unsaved section — for example, by calling the API before the auto-save has written the current geometry to the database — returns a 428 Precondition Required response with code section_not_saved.
In the editor, this is transparent: the Calculated badge only appears after the auto-save completes, and the Report button and Mesh button are disabled until then. API and MCP callers should treat section_not_saved as a signal to wait for the save to land before re-requesting, not as a permanent refusal — the section is not invalid, just not yet persisted. The previous behaviour silently ran properties against stale or phantom geometry whenever the save had not yet committed.
:::
Two-path model
| Path | When it runs | Badge | Scope |
|---|---|---|---|
| Client (browser) | Immediately on every geometry change | Preview | Instant feedback while drawing |
| Server (authoritative) | Automatically once the auto-save lands and the server returns properties for the saved geometry | Calculated (green) | Authoritative results; drives the PDF report |
The two paths use identical algorithms — Green’s theorem for area/centroid/inertia, Sutherland-Hodgman clipping for plastic moduli — so the Preview and Calculated values agree to floating-point precision for simple (polygon-only) sections. For sections with arc edges the exact exactRingProperties algorithm eliminates discretisation error in both paths.
They also agree on what they refuse. A section whose net area — geometric or stiffness-weighted — comes out as zero or negative has no meaningful properties to report, and both paths decline to produce numbers rather than returning a figure that would look like an answer. See Error states.
Preview badge
The Preview badge appears as soon as the section has at least one valid outline. Preview values are computed in the browser and update live as you drag vertices or change material assignments. Use them for rapid iteration — they are correct for well-formed sections, but the server result is the one that goes into the report.
Calculated badge
The Calculated badge (green) replaces Preview once the server returns a successful result. The server validates the geometry first (see Error states below) and then runs the full property pipeline. The Calculated result is the authoritative value for the section; the PDF report uses this same path — there is no third computation.
If the server validation finds a problem, the badge shows an error state and the sidebar displays the diagnostic code. Fix the geometry and the server re-validates automatically.
Error states
If the geometry cannot be analysed, the server returns a structured error and the sidebar shows an explanatory notice with an error code:
| Code | Cause | Fix |
|---|---|---|
self_intersection | The polygon crosses itself, or touches itself — two non-neighbouring vertices on the same point, pinching it into lobes | Reorder or move the conflicting vertices |
void_outside_outline | A void region extends beyond the parent outline | Shrink the void or enlarge the outline |
overlapping_regions | Two regions share interior area in a combination that has no physical reading — two outlines, two inclusions, an inclusion and a void, two voids, or an inclusion partially crossing an outline boundary. An inclusion strictly contained in an outline is the embedded composite and is accepted | Separate them, move the inclusion fully inside the outline, or convert one to a void of the other |
no_outline | A void region is present but the section has no outline for it to be carved from. A section with no outline but no void either — inclusions only — is valid and is not affected | Add the enclosing outline, or delete the stray void |
insufficient_vertices | A region has fewer than three vertices | Add more vertices to close the polygon |
non_finite_coordinate | A vertex has a NaN or infinite coordinate | Review parametric inputs for degenerate dimensions |
zero_net_area | The voids subtract the outline’s entire area — most often a void drawn coincident with the outline it sits in. The geometry itself is well formed, so the region checks above all pass | Shrink or delete the void |
zero_transformed_area | The stiffness-weighted area is zero or negative. Two configurations produce this: (1) a void carrying a much stiffer material than the outline cancels the outline out via the modulus-weighted subtraction, while the plain geometric area stays healthy; (2) every region in the section is assigned a material with zero elastic modulus, so no region contributes any positive stiffness-weighted area. Prior to the August 2026 release (#5179), configuration (2) was not caught before the solver ran and produced a division-by-zero in the transformed-property pipeline — the panel displayed an incorrect result or NaN values rather than refusing. Both configurations are now refused before any properties are computed, consistent with §874. | For configuration (1): shrink the void, or reassign materials so the weighted subtraction no longer swallows the section. For configuration (2): assign a non-zero elastic modulus to at least one solid (non-void) region. |
Error states clear as soon as the geometry passes validation. While any of these codes is showing, the properties panel is blank rather than falling back to Preview values. That is deliberate: a client-side figure for a section the server has just called invalid is not an approximation of the right answer, it is a meaningless one, and showing it would be worse than showing nothing. The Preview keeps rendering only for transient failures — a dropped connection, a 5xx — where nothing has been said about the geometry.
The last two differ from the six above in where they are caught, not in what the panel does. zero_net_area and zero_transformed_area are refused by the browser on its own, before any server round-trip, by the same explicit guard the server applies: the quantity every other property is divided by is zero or negative, and both implementations stop rather than divide. So these two blank the panel the moment you draw the configuration, without waiting for a server exchange to tell them to.
:::note[Arc-ring fold validation at grid edit time — September 2026 (#5450, #5475)] Fold validation for arc-ring sections is now caught and reported during grid editing, not at analysis time. If the grid editor shows a fold validation error while you are editing an arc-ring section, fix the geometry in the grid before attempting to run an analysis. Previously, a fold-invalid arc-ring section could be submitted to the analysis pipeline, which only reported the error at that point — the current release surfaces it at input time, where it is easier to correct. :::
PDF reports
Once the server has produced a Calculated result, click the Report button in the top action bar to generate a PDF. The button opens a Full report / Summary report dropdown menu:
| Option | Contents | Filename |
|---|---|---|
| Full report | Complete property set — all geometric, elastic, plastic, and transformed properties with formulas and derivation steps | {name}_Report.pdf |
| Summary report | Condensed property set — area, centroid, second moments of area, elastic moduli, and transformed centroid (for composite sections) | {name}_Summary_Report.pdf |
Special characters in the section name are replaced with underscores. The Report button is disabled while the section has no Calculated result (no valid geometry has been analysed server-side yet).
The same analysis pipeline runs for both variants — the variant controls which properties are rendered in the document, not which calculations are run. The PDF always reflects the authoritative server result, not the client Preview.
Composite sections
For composite sections (more than one material assigned across the section regions) the panel additionally shows transformed (stiffness-weighted) properties under a separate heading. These are computed using the modular-ratio method: each region’s area is scaled by the ratio of its elastic modulus to the reference material’s modulus. The transformed centroid is the elastic neutral-axis position for the composite.
See Section properties reference — Transformed properties for the full field list and formulas.
Mesh overlay
The Mesh button in the canvas toolbar requests a triangulated mesh of the current section. The mesh is a display overlay only — GCS analyses geometry analytically, so the mesh has no effect on section properties or any reported quantity.
The mesh endpoint is GET /api/v1/gcs/design-options/{designOptionId}/mesh. It is a metered derived read at 80 µ$ per call; the cost appears in the API usage log against the design option.
Updating state
The mesh overlay shows a · updating badge while the persisted geometry may lag behind the most recent save. This occurs when a geometry edit is still in the debounce window and the new geometry has not yet been written to the server. Once the save completes and the server returns a fresh mesh, the badge clears. Previously the panel rendered nothing in this window; the updating badge now shows the last-successful mesh in place with a clear disclosure that it may be stale.
Mesh refusals
The endpoint refuses and reports an error in two cases:
| Code | Cause | Fix |
|---|---|---|
mesh_requires_single_outline | The section has no outline region — only inclusions or voids with no enclosing boundary. A mesh requires exactly one outline to triangulate within. | Add an outline region that encloses the inclusions or voids, or delete the regions and redraw with an outline. |
mesh_requires_single_outline | The section has multiple outline regions. The mesher requires exactly one outline to triangulate within. | Merge the outlines into one, or delete all but one. |
:::note
The error code mesh_requires_single_outline covers both the zero-outline and multi-outline cases — the remedy differs but the code is the same. Prior to this change, both configurations were meshed silently, which caused inclusions without an enclosing outline to be triangulated as holes in a non-existent boundary. That mesh was geometrically incorrect (§874); both configurations are now refused.
:::
Mesh and inclusions
When the section contains inclusion regions — composite inserts that have a different material to the outline — the mesh overlay does not conform to the inclusion boundaries. The triangulation covers the whole outline polygon; inclusion boundaries are not drawn as internal edges. This is a display limitation only. GCS section properties treat inclusion regions analytically: each region’s area and stiffness-weighted area are computed from its declared geometry, independently of the mesh overlay.
Related pages
- Getting started with GCS — first analysis walkthrough
- Materials — material assignment and composite sections
- Section properties reference — every output field with its formula and units
- Limitations — what the analyser does not compute