API Companion Guide

This is the hand-written companion to the autogenerated API reference. The autogenerated pages give you every public symbol and its raw signature; this guide explains what each type is for, when to call each method, what the arguments mean in practice, and what to watch out for — with a worked example on every section.

If you want a function signature, look in the API reference. If you want to understand the shape of FOSSIL's public surface, read on.

The 60-second tour

FOSSIL exposes a single Fortran module:

use fossil
use penf, only : I4P, R8P

That module re-exports three types and three families of named constants:

Symbol	Kind	Role
surface_stl_object	type	A whole triangulated surface — I/O, repair, manipulation, distance and inside queries.
facet_object	type	A single triangular facet — vertices, normal, connectivity, pseudo-normals.
aabb_tree_object	type	The acceleration structure embedded inside every surface (SAH BVH or octree).
SIGN_*	constants	Sign algorithm for signed-distance queries (pseudo-normal / ray-cast / solid-angle).
AABB_TREE_*	constants	Choice of acceleration structure when loading or analysing a surface.
STATUS_*	constants	Return codes from the optional status argument on mutating procedures.

The canonical workflow is:

program ex_overview
use fossil
use penf, only : I4P, R8P
use vecfor_R8P, only : vector_R8P
implicit none
type(surface_stl_object) :: surface
type(vector_R8P)         :: p
real(R8P)                :: d

call surface%load_from_file(file_name='cube.stl', guess_format=.true.)
call surface%sanitize
p = 0.5_R8P * surface%get_bmin() + 0.5_R8P * surface%get_bmax()
d = surface%distance(point=p, is_signed=.true., is_square_root=.true.)
print '(A, ES12.5)', 'centre-of-bbox signed distance = ', d
call surface%save_into_file(file_name='out.stl')
end program ex_overview

1. Load an STL (auto-detect ASCII vs binary, build the AABB tree, populate pseudo-normals for the default sign algorithm).
2. Sanitize — repair degenerate / duplicate facets, snap nearby vertices, propagate winding consistency, orient normals outward.
3. Query — point-to-surface distance (signed or unsigned), inside-or-outside tests, validity predicates, descriptive statistics.
4. Manipulate — clip, rotate, translate, mirror, scale, merge with another surface.
5. Save the result.

That is the full public arc of the library.

How to read each page

Every public type-bound procedure on the four pages below follows the same six-block template:

Signature — a fortran block with a call site that compiles against the current API.

Purpose — one paragraph in plain English: what the method does, why it exists, what state it changes.

Arguments — one entry per argument, marked in / out / inout and (required) / (optional), with the type and a sentence on the contract.

Example — a complete, runnable program. Every snippet on these pages is extracted and compiled by CI; if it compiles here, it compiles for you.

Notes — caveats, complexity, interactions with other methods, "common mistake" callouts. Read these.

See also — cross-links to related methods, the constants they consume, and the autogenerated reference page.

Pages

• Constants — SIGN_*, AABB_TREE_*, AABB_AUTO_REFINEMENT, STATUS_*. Read this first: every method on the other pages takes one or more of these as optional arguments.

• surface_stl_object — the library's centrepiece. Load, save, sanitize, analyse, query, manipulate. ~20 public TBPs.

• facet_object — a single triangle. You rarely instantiate one yourself; instead you walk over them via surface%facet_at(i). ~8 public TBPs plus a small set of data members.

• aabb_tree_object — the acceleration structure inside every surface. You configure it via the optional aabb_tree_kind / aabb_refinement_levels arguments on surface%load_from_file and surface%analyze, and inspect it via surface%aabb%….

What this guide does not cover

• Low-level facet I/O (facet%load_from_file_ascii, etc.) — used internally by surface%load_from_file and not part of the public contract. See the autogenerated reference if you really need them.
• The internal block / vertex-pool / id-list modules (fossil_block_object, fossil_vertex_pool_object, fossil_list_id_object) — implementation details of surface_stl_object and aabb_tree_object.
• Test programs under src/tests/ — they are exhaustive usage examples, not API. Read them when you want to see edge-case handling, not when you want to learn the public surface.

Examples and CI

Every ```fortran``` block on these pages is a complete, self-contained program that compiles against the installed library. The .github/workflows/docs-snippets.yml workflow extracts every snippet and compiles each one on every push. If a signature changes and a doc example drifts, CI fails before the change is merged.

The script that does the extraction is scripts/check_doc_snippets.sh; you can run it locally before committing doc changes:

./scripts/check_doc_snippets.sh