Part of the architecture notes indexed in AGENTS.md. Keep each topic in its bullet here; AGENTS.md only lists the topics.
cc_core::site: ProjectInfo::site (Option<SiteLocation>: latitude, longitude of the project origin in WGS 84 degrees, elevation above sea level, true_north degrees counter-clockwise from project +Y, place, SiteAddress parts; repair drops a location off Earth) and the conversion to project meters (east_north on the plane tangent at the site, to_project/from_project with true north; to_dms/from_dms for IFC). cc_engine::osm is pure: read turns an Overpass JSON answer (out geom or nodes) into a CadDrawing in meters (layers Layer::ALL, street names along the longest stretch, lines clipped to the square, multipolygon outer ways joined) and Building footprints with heights (height, building:levels, else Options::default_levels), overpass_query builds the query for the square, read_places/read_reverse/read_elevation read Nominatim and elevation answers; bounded. Commands in cc_engine::commands::site: site_get, site_set (patch; address parts rewrite ProjectInfo::address), site_context_import (one undo step: a pinned CadImport at the origin plus a mass per building of the “Context” mass type, no mass floors). IFC export writes IfcSite RefLatitude/RefLongitude (compound angles), RefElevation, LongName, SiteAddress (town, region, postcode, country) and true north in the model context; import reads them back. In the app, site_ui.rs (Manage → Project → Site Location): an in-house slippy map (OSM tiles over two ureq threads, in memory), Nominatim search and reverse (one request per second, on request only), Open-Meteo elevation, the marker fixed at the center and the square turned with true north; network never in tests.cc_core::sun: View::sun (Option<SunSettings>, only on views that ViewKind::takes_sun: plans, ceiling plans, 3D views, elevations, sections; serde default, no format bump) holds a SunMode (Still date and time, SingleDay/MultiDay studies of SunFrames every SunInterval, sunrise to sunset or not, bounded by MAX_FRAMES/MAX_DAYS; Lighting azimuth and altitude, relative_to_view), the frame shown, show_path, shadows and the ground level; Project::sun_presets (SunPreset, tracked as settings, EditCtx::sun_presets_mut) are named modes. The solar position is the low-precision public formulas (solar_position, daylight with refraction at HORIZON_ALTITUDE, day_path), deterministic; Project::sun_site reads the site (SiteLocation::utc_offset, else the longitude’s zone, offset_hours; the equator at Greenwich without a site) and SunSettings::state/Project::sun_state give a SunState (azimuth, altitude, unit direction in project coordinates turned by true north, the frame, above_horizon), a view-relative light measured from view_forward (camera_forward for a live camera). Repair keeps suns on views that take them, values in range (SunMode::repair, repair_presets) and the ground on an existing level; EditCtx::finish → sync_sun_ground drops a deleted ground level. cc_views::sun_path: diagram builds a SunDiagram in world coordinates (compass ring turned to true north on the ground level, ticks, axes, the day’s path on the dome with its hours, a multi-day study’s first and last days, sunrise, sunset, date and the sun; bounded by MAX_POINTS, finite), draw lays it over plans and projected views as the Drawing2D::overlay (no element, not picked, snapped or cropped, but fitted; horizon labels past the ticks, label_anchor, the date stacked beyond the sunrise time, stacked_on), and Look::light lights shaded and textured projected views from the sun (ambient only below the horizon). The sun’s shadows in 2D views (SunSettings::shadows, in the styles VisualStyle::colored: plans, elevations, sections and the 2D form of 3D views; never hidden line or wireframe) are exact polygons, cc_views::shadow: Look::shadows (Shadows: the ground height, Project::sun_ground_height, the rule the 3D view and the path tracer share: the sun’s ground level, else the lowest level, else the model’s bottom; and a Skip of the elements the view’s Resolver hides, which cast and catch none, or makes see-through, which cast none, shadow_skip in generate_temporary) makes projected::render build a Scene of casters: every opaque face not edge-on to the sun, a closed convex solid (convex) as one unit that casts the hull of its points, of the model beyond the frame’s near plane closed by the cut’s caps (caps), in a grid over the units seen from the sun. Which faces catch them is the view’s shadow::Catch, as drawings are read. All (elevations, the 2D form of 3D views): everything shown casts on everything shown. Site(&Indoors) (floor plans, set by plan::style_underlay) reads the site: the whole model the view shows casts, what stands above the cut plane too, on every face seen from above and on the ground as the sun does (under an eave, a porch or a pergola too), but for what is indoors. Outdoors(&Indoors) (sections): the model in front of the section’s line casts nothing, and faces indoors catch nothing. Indoors::of (made in generate_temporary for both) finds storey by storey (from a level to the next; the walls standing STOREY_PROBE above the level) the spaces the walls’ outlines close (cc_geom::RoomArrangement::spaces: rooms whether or not a room element was placed, and the walls’ own bodies) that slabs cover by more than INDOORS_COVER, united per storey; what covers is a floor, roof or ceiling (shadow::covers, by solid category; beams, such as a pergola’s, and foundations do not), cast straight down by a second Scene (Scene::covers). A point is indoors when it is in a space of the storey at its height (Indoors::holds) and a slab of another element lies above it (Scene::above), so the top of a roof never is. A section takes a face whole, by the point FACE_PROBE in front of it (point_within): the rooms cut show their plain shading and a wall under an eave, which looks onto the open, keeps the eave’s shadow. A floor plan takes the part of each face that is indoors (Scene::indoors_on: the slabs over the face within the spaces of the storey PLAN_PROBE above it; a face wholly in a space, encloses, and wholly covered is skipped) and of the ground out of their shadows (region::covered_except). Ceiling plans draw none (Look::casts_shadows). For each drawn opaque face turned to the sun, Scene::on_face slides the casters standing in front of its plane (LIFT) along the sun’s rays onto that plane (cast: cut to the face, or to its box when it is not convex; one that covers the face ends the search, those inside a convex one are left out) and unites them (rings; more than twice UNION_GROUP of them a group of neighbors at a time, then the groups’ unions together, which costs less), and Scene::on_ground does the same on the ground plane when the view looks down (no farther than a sun 5° up reaches). The union is cc_geom::region::covered (covered_except leaves out what other polygons cover): the polygons’ edges welded (weld: points within TOL one point, edges split where they cross and at points on them; more rounds only when the triangulation still meets a crossing), a constrained Delaunay triangulation of them (spade, in catch_unwind), each triangle in or out by its centroid (a triangle of no height with the region on both sides of its line, across a row of such triangles, is a gap of rounding and closed; with the region on one side only, points in a line along a side, it is not), the outline between them chained into rings with their holes keyholed (pieces; a hole inside no outline is a failure, never a region without the hole); bounded by MAX_EDGES and MAX_WELD_WORK. The rings are drawn as black veils that belong to no element (not picked, not overridden; DXF leaves them out), the ground’s first and a face’s right after its fill and under its lines; shadow::veil gives the opacity that leaves VisualStyle::SHADED_SHADOW of the lit grey (the textures and consistent colors styles darken alike; fading out edge-on, as the 3D view), ground_veil the 3D ground’s. Bounded by MAX_CASTERS, MAX_LOOKS, MAX_UNION_POINTS and MAX_POINTS: past one the view draws no shadows at all. cc_render::Light (direction, shadows, ground height) through Renderer3D::set_light (None: the camera’s light; frames and the shadow map are redrawn only when it changes): shadow.rs makes the sun’s pipelines on first use and the 2048² shadow map only when a light first casts shadows, sun.rs fits the orthographic light view to the scene and the ground quad that catches shadows. SunMode::conventional() is the façade drawing’s sun (Lighting relative to the view at CONVENTIONAL_AZIMUTH 225° and conventional_altitude() atan(1/√2): rays along a cube’s diagonal from over the viewer’s left shoulder, so a shadow falls down and to the right as far as its caster stands out; is_conventional), and SunSettings::default_for gives elevations and sections that sun with shadows when they first get one (the app’s Sun Settings dialog). Commands in cc_engine::commands::sun (view_set/view_get sun through SunArg, "mode": "conventional" resetting to that sun, derived.conventional, sun_position, sun_frames, sun_preset_save, sun_presets_list, sun_preset_rename, sun_preset_delete; site_set utc_offset). The app: sun_ui.rs (the Sun Settings dialog, View → Graphics → Sun Settings and the Sun row of view properties; OK/Cancel through graphics_dialog::Edits, a saved document left unchanged stays saved) and sun_overlay.rs (SunView, cached per revision, and for a view-relative sun per live camera yaw: the 3D view’s Light, its ground the rendered image’s cc_raytracing::environment::ground_height (the sun’s ground level, else the lowest level), and the diagram painted over the image through modify3d::Frame::segment, clipped at the near plane); the view cube’s compass turns to true north.cc_core::render_settings: View::render (Option<RenderSettings>, only on views that ViewKind::takes_render; serde default, no format bump) holds samples, max_depth, width, height, fov_deg, exposure (stops), tone_map (ToneMap::Filmic/Standard), the firefly clamp, clay and a RenderEnvironment (sky_strength, sun_strength, ground_color, ground_plane), bounded by the module’s MIN_*/MAX_*/DEFAULT_* constants and MAX_PIXELS; is_valid/repair, and repair on load drops settings from views that do not take them and brings values into range. cc_raytracing path traces on the CPU through sort-raytracing: RenderScene::build(project, geom, view, camera, settings, temporary) takes the view’s geometry and leaves out what the view’s graphics resolver hides (visibility, phase, options, temporary hiding), applies its color, transparency and halftone overrides, its detail level, painted faces and material textures laid as the textures style lays them, with smooth normals across curved facets; space turns Z up into the tracer’s Y up ((x, y, z) → (x, z, -y)) about the model’s center for f32 precision; materials maps a Finish to roughness and shine, metals to metallic, glass (class Glass or at least GLASS_TRANSPARENCY transparent) to thin glass the sun passes through, other transparency to coverage, textures decoded once (Textures, MAX_TEXTURES, MAX_TEXTURE_SIDE), and clay every opaque surface to CLAY_COLOR matte (glass kept); environment generates the sky map (sky_map, ENV_WIDTH×ENV_HEIGHT), the ground and a distant sun from Project::sun_state (sun_state; a view without a sun gets default_sun, DEFAULT_SUN_ALTITUDE high at DEFAULT_SUN_AZIMUTH from the viewer), the ground plane at ground_height (the sun’s ground level, else the lowest level, else the model’s bottom); camera::eye_and_forward and camera::fit (a never moved camera fitted to the picture’s field of view and aspect); run refines a few samples at a time with a callback returning Control (stop between steps) and an optional Region, render_image renders to the end, and Image holds linear radiance (to_rgba8 exposes and tone maps, save writes PNG, JPEG, EXR or HDR); scenes past MAX_TRIANGLES are refused, degenerate triangles dropped, and every call into the library runs in catch_unwind (guarded), a panic becoming RenderError::Internal. plane_axes and Solid::facet_shifts live in cc_geom (shared with cc_render). The engine: view_set/view_get render (a merge patch through views::apply_render; null removes it) and view_render (cc_engine::commands::render: view, path, settings patched for this render only, region [x, y, width, height]; the view’s camera, fitted when never moved, rendered as printed; returns path, width, height, samples, seconds, triangles; changes nothing). The app: render_ui.rs (View → Graphics → Render, UiCommand::Render, available on views that take render settings): a modal window with the picture and the view’s settings, rendering on a render thread and a display thread with a stop flag and a generation per render so late pictures are dropped; settings written through engine_edit::view under one merge key (one undo step); exposure and tone map remap the linear image without tracing again; Region, Save Image…, and Sun Settings…, which hides the window and reopens it through Dialogs::render_resume.