Data model map#

A map of the data OpenOHL keeps: the line model, the libraries it refers to, the files they live in, how objects point at each other, and what a plugin sees. It is written for plugin builders and contributors; the user guide pages linked below give the full field lists of each file.

Keeping this map up to date. Any change to a model struct (ohl-line, ohl-structures, the library crates), a file format (line file, OHL XML, library files, the project file's tables) or the plugin interface (crates/ohl-plugins/wit/*.wit, the export model, the Python ohl module) updates this page in the same commit. If a field is added, renamed or removed, or a reference changes from an id to a label, the diagram and the tables below change with it.

Known weak points and proposed changes: Data model review.

All examples on this page are invented (structures T1, T2, sections S1, a system sys-A, …).

Overview#

                                  LINE  (.ohl.json / OHL XML / project rows)
 ┌──────────────────────────────────────────────────────────────────────────────────┐
 │ meta: name, crs, display, systems[], creep_stretch, bimetallic, solver,          │
 │       defaults, circuit_starts[], structure_loads                                │
 │                                                                                  │
 │  Route {id, name} ◄──route── Alignment ──points[] (ids)──► AlignmentPoint {id}   │
 │     ▲                     (one route)      (a point: 0..n alignments) structure?┐ │
 │     └────────── routes[] (given) ── Structure ◄─────────────────────────────────┘ │
 │                                        │  id, position, orientation_deg          │
 │                                        │  type ─────────────────────────────┐    │
 │                                        ├─ points[]  StructurePoint (label)  │    │
 │                                        ├─ wires[]   WirePoint (label, set?) │    │
 │                                        └─ strings[] InsulatorString         │    │
 │                                              top ─► point/wire label        │    │
 │                                              wire ─► wire label             │    │
 │                                              insulator ──────────────────┐  │    │
 │                                                                          │  │    │
 │  Section ──points[] : SectionPoint {structure, set}──► WirePoint.set     │  │    │
 │   │  cable ───────────────────────────────────────────────────────┐      │  │    │
 │   │  system ─► System.id,  phase_label ─► SystemPhase.label       │      │  │    │
 │   └─ stringing, span_points[] {label, span (index), at, object?}  │      │  │    │
 │        spreads[] {from, to ─► span point labels}, calculation     │      │  │    │
 │                                                                   │      │  │    │
 │  Spacer ── a / b : {section, point} ─► SpanPoint.label            │      │  │    │
 │   └─ insulator ──────────────────────────────────────────────────┼──────┤  │    │
 │                                                                   │      │  │    │
 │  Jumper ── from / to : JumperEnd — SectionPoint ─► WirePoint.set  │      │  │    │
 │   │      or {tap: {span: {section, point}}} ─► SpanPoint          │      │  │    │
 │   │      or {tap: {jumper: {jumper, point}}} ─► JumperPoint       │      │  │    │
 │   │  cable ───────────────────────────────────────────────────────┤      │  │    │
 │   ├─ points[] JumperPoint {label, at, object?}                    │      │  │    │
 │   │     object.hold (a support): strings {structure?, wire ─► WirePoint.label} │
 │   │                              or string {point, length, weight}       │  │    │
 └───────────────────────────────────────────────────────────────────┼──────┼──┼────┘
                                                                     ▼      ▼  ▼
                         LIBRARIES (TOML, units in the values)   .ohlw   .ohli .ohls
   .ohlload point and spread load types ◄── LineObject.type, SpreadObject.type   │
   .ohlwc weather cases ◄── creep_stretch names, LoadCase.weather          ▲     │
   .ohllc load cases                                                       └─────┘
                                                        TypeString.insulator ─► .ohli id
   .ohls StructureType: point[], wire[], string[], extension[], node[], member[],
                        section[], material[], load[], load_case[], capacity, wind,
                        model ─► .ohlfe, pole ─► .ohlp (or [pole] in the file),
                        extension[].node[]/member[]/leg[] (pieces below the feet),
                        template (built from ─► .ohlpt)
   .ohlslc structure load cases (load_case[]; structure application) ─► labels of
                        .ohls points, sets, member ids; line_case ─► LoadCase.name
   .ohlpt PylonTemplate: parameter[], attachment[] (slot, across, up),
                        earth[], strings ─► builds a level-1 .ohls
   .ohlsec SectionLibrary: material[], section[] (shape, dimensions,
                        material ─► material id) ◄── member section
                        (.ohls / .ohlfe; the library first, then [[section]])

Arrows point from the referring field to what it names. Everything inside the box belongs to one line; the libraries are shared and referred to by id (or, for weather cases, by name).

Conventions#

Units#

• Line model (.ohl.json, OHL XML, project rows): plain numbers in SI — metres, newtons, N·m², m², °C for temperatures. A field name says when it is not: _deg degrees, _kv kilovolts, _hz hertz. Colours are #rrggbb.
• Library files (TOML): values carry their unit as text ("12.5 m", "1.4 kN", "400 mm²", "20 °C"), converted to SI on reading (ohl_core::units; a plain f64 field reads so through units::si::de); a plain number is SI. A bare number is otherwise a factor or a count. Exceptions, where the key or the file says the unit: angles in degrees (tilt, _deg: a plain number is degrees, text may give "0.17 rad", units::si::de_degrees), _kv keys, prices (in the cost file's currency).
• Inside the program every quantity is SI (Conventions and units).

File headers#

Every OpenOHL file may start with format (its id, e.g. ohl-wire) and version; both optional. A file of another format is refused; any version up to the program's is read (older ones converted), a newer one refused ("written by a newer OpenOHL") — one check for all, ohl_core::files::check_header (the line file and OHL XML, check reports and colour palettes too; plugins' own files, as .ohlpd, the same way). A key a format does not know is refused, naming it (a typo is said, not left out); crates/ohl-cli/tests/format_typos.rs checks every library format (the structure application's in apps/structure/ohl-structure-tests/tests/format_typos.rs). Objects on points are read through LineObjectFile / ObjectTypeFile for that (a flattened shape would let keys through), a size of another shape or a missing size said too.

Names of before 2026-10-18 are read: the ols extensions (.ols, .ols.json, .olsw, .olss…) and format ids (ols-wire, ols-structure, OLS XML's namespace urn:ols-cad:ols-line:1) are taken for their ohl names (ohl_core::files: check_header, has_extension, files_with_extension, is_project_file, line_file_stem; a folder holding both a.olsw and a.ohlw reads the latter); new files are written with the ohl names. A project's library files keep the names they were stored under. Plugin manifests ols-plugin.toml are read too; plugins of the ols:plugin interface (sdk 0.2) are refused until rebuilt for ohl:plugin (sdk 0.3). crates/ohl-cli/tests/older_names.rs checks the example line and libraries as they were then (tests/data/before-ohl) against the current ones.

New optional fields raise the format version (review rule 2.12: an older program then says "newer version", not "unknown field"). The string limits (max_load, the swing limits — optional, not checked by OpenOHL, for plugins and reports) did so: line file 6 (OHL XML follows it), .ohls 4, .ohli 2. The .ohls and .ohli writers write the newer version only when a limit is given (an older program still reads the rest); the line file is always written at the current version. A new value counts as a new field: the member kind tension (a truss in tension only) made .ohls 5 and .ohlfe 2; the structure application raises a file to 5 when it makes a member tension (ohl_structure_edit::set_member_kind), and only then. The export model's member kind (CSV, IFC TENSION_MEMBER, SAF "Tension only") takes the value tension too. The export model JSON stays version 1 (keys only added: strings per case) and the plugin WIT is unchanged (no record passes strings).

Coordinates and angles#

• Structure.orientation_deg: the direction of the local x axis (the right of the line), degrees counter-clockwise from east (mathematical sense). Ahead (local +y) is a quarter turn counter-clockwise from it.
• ohl_structures::structures::to_global(position, rotation_deg, local) rotates a local point counter-clockwise by rotation_deg and adds position; to_local is its inverse. A placed type's points are also raised by the extension's dz, the type's foot and the structure's height_adjust.
• Display.ahead_deg is only a display convention: the user interface shows plan directions around a structure (string directions, the compass) as angles turning clockwise seen from above, and ahead_deg is the angle that means ahead (default 0: ahead 0°, right 90°; with 270: right 0°, ahead 270°). A displayed angle a points to the local direction (sin φ, cos φ) with φ = a − ahead_deg. No stored coordinate depends on it; a plugin reading or writing points ignores it.
• Stations and offsets are horizontal; offsets are positive to the right looking ahead. A route's line angle is positive turning right.
• The wind side ("from the right") is taken looking ahead along the nearest route segment (Conventions).

The line (ohl_line::Line)#

Source: crates/ohl-line/src/lib.rs. One line per .ohl.json file and per project line in a project file. Full field reference: Line files.

Plugin values (fields, ohl_line::Fields): structures, sections, jumpers, systems, alignments and routes carry a map plugin.column → text, the values of the table columns plugins add ([[column]] in a plugin's manifest, Writing plugins). Empty maps are not written. Kept with the object through every edit, written to OHL XML as <field key value>; shown (unused) where the plugin is not installed. A circuit's values are on all its sections. A check plugin reads its own (ohl_clearance::phase_distance passes the sections' values to it).

Route, Alignment and AlignmentPoint (route.rs)#

A point's place on each alignment it is on is its index in that alignment's points; a point on several alignments (a junction) is one object with a place in each; a point on none waits to be used. Its routes are those of its alignments (Line::point_routes). Deleting a point takes it off every alignment (Line::delete_alignment_point); deleting an alignment keeps its points.

What is on a route is worked out, not stored (Line::structure_routes, Line::wire_routes, Line::alignment_views):

• a structure tied to an alignment point, or within 5 m of an alignment (NEAR_ALIGNMENT, beside it or within 5 m of an end), is on that alignment and its route; a structure giving its own routes is on those (stationed on the nearest alignment of each); at a junction it is on every route meeting there;
• a section is on the routes of its structures (one running from a route into another is on both); a jumper on those of its two ends; strings, wire points and counterweights on those of their structure.

AlignmentView (id, route, points, structures in station order, and away: those of them neither tied to one of its points nor within 5 m of it — on its route because they give it themselves, such as a connection beside the line) is what the profile, drawings, stationing and spotting work on; each structure on an alignment gets a station there (Station: station, offset, line angle, ahead span — computed, not stored). The run along the alignment (AlignmentView::run) leaves the structures away out: line angles and spans ahead are taken along it (a structure away has 0 for both), and the profile's spans are those between consecutive structures of the run (AlignmentView::consecutive) plus those to a structure away (projected), so a connection whose station falls between two towers does not break the span between them.

Files of version 2 held routes that were their own alignment (alignment, structures) or followed their structures, and the line's own alignment without routes: Line::upgrade_routes (on reading) makes each a route and an alignment of the same id — points tied under the structures for one that followed them, the line's own named main — and gives a structure its routes itself where the alignments would not find it on them. Files of version 3 held alignments on one or more routes with their points inside ([x,y,z] or {position, structure, routes}): the points become alignment points (P1…), the same place on several alignments (1 mm, compatible ties) one shared point; an alignment on several routes one alignment per route (a, a (route)); a point's own routes go to its tied structure. Projects are converted once when they open (ols_meta keys routes_alignments, alignment_points).

Structure (lib.rs, assembly.rs)#

A structure without a type holds its own points, wires, strings and members; the desktop app edits them as a structure type in local axes (to_local/to_global) and writes them back with one Put. Make it a type writes that document as a .ohls, sets type and empties the structure's own lists. A type built from a pylon template records it in [template] (id, role suspension/strain, string_length, string_weight, values by parameter) and has sets from the template's slots: suspension = slot, strain: the first string (180°) slot + first_offset (20), the second (0°) slot + second_offset (40); files before give back_offset / ahead_offset. Built again, only the header, [template] and the points, strings and wire points the template makes (by label) are replaced; the rest of the file is kept (ohl-app pylon_builder::rebuilt).

The string graph: a V-string is two strings to one wire point; strings hang from strings (a V with a string below, a TAK). A wire point no string reaches is fixed to the structure. A string's length and direction place its wire point (Line::place_strings, when a line is read or resolved): top + length × direction; a V's wire point where its first two legs' lengths meet, the point of that circle nearest where the first leg's direction points (their directions follow). Strings without a length (files written before) take it and their angles from where their wire point is, so nothing moves. There is no "ahead"/"back" for a string: its angles alone give its direction. Version 1 files gave one attachments entry per set and phase; they are read through AttachmentV1 and set_from_v1(set, phase) (set for phase 1, else set + 1000·(phase + 1)).

Typed structures. With a type, the file keeps only the overrides: Line::resolve (crates/ohl-line/src/library.rs) places the type (to_global with orientation_deg, the extension, height_adjust), then the structure's own items replace the type's by label, a wire point with a set replaces the type's wire point with that set (and what moves with it), omit/omit_sets leave items out, weights, stiffnesses and wind areas come from the insulator library where a string has none (a V-string assembly's shared by its legs), and the wire points are placed from the strings. In a weather case the jumpers load the clamps of the sections at their ends, as the line's solver.jumper_loads says: an estimate (jumper::end_loads: weight, ice and wind of the jumper between an end and its first support) or the solved jumper's own pull (solve::jumper_pull) — not at stringing. The resolved line is what solvers and exports use; the stored line and the project rows are not resolved. A typed structure's own strings may hang from the type's points: as stored, such a top is not checked and its wire point is not placed (Structure::check_strings_as_stored, place_wires); once resolved every structure is checked in full (check_strings).

Section (lib.rs, condition.rs)#

SectionPoint { structure, set } names the wire point with set set on structure structure. Spans are between consecutive points.

Stringing is tagged by kind:

LineObject (objects.rs): kind (body | clamp — a clamp holds a jumper or a spacer, a hinge passing forces only), type (the library type it was taken from; its values are its own), weight (N, whole bundle), its shape flattened (shape = point | sphere (diameter) | cylinder (diameter, length, axis along / across / vertical) | box (along, across, height) | areas (wind_area, ice_area)), drag, clamp_length, and on a jumper's clamp hold — what holds it up, making it a support: {"strings": {"structure"?, "wire"}} (the strings of a structure to a wire point without a set, an I or a V; structure default the jumper's from) or {"string": {"point", "length", "weight"}} (one tension-only string from a fixed point). Loads in a case (LineObject::forces): weight, the wire's radial ice on its surface (a sphere's shell; a layer on the other shapes' surfaces), the wind on its iced projected area across the line, times its drag. A clamp's shape is drawn as given — a cylinder across the line on a bundle joining its subconductors (drawn only) — and takes wind and ice as a body's of that shape and size; without a shape (point) it is drawn as a short cylinder along the wire, its clamp_length, and takes no wind nor ice.

Older files (and OHL XML <load>, <spread_load>) gave point loads (loads: legacy::SpanLoad — span, place, vertical, label, diameter, drag, wind_area, ice_area) and spread loads (spread_loads: legacy::SpreadLoad, span, start, end, load, label): read into a point L1, L2… holding a body (a sphere of the diameter, or the given areas; the label its description), and into two bare points S1, S2… with a spread between them; written in the new form.

Point and spread load library (.ohlload)#

ohl-point-spread-loads, version 1 (objects::ObjectLibrary): name and [[type]]s — id, name, description, kind (body, clamp, spread), weight, the shape as on objects, drag, clamp_length, a spread type's load (N/m) and per_subconductor (optional, spread types only: its load on each subconductor); sizes, weights, lengths and loads with their unit ("600 mm", "70 N", "12.5 N/m") or plain SI numbers. Shipped templates (typical values, to check): libraries/objects/templates.ohlload. A project's own types are a project library file of kind objects (project.ohlload), over the templates of the same ids (Sections › Point and spread load types).

Jumper and JumperClamp (lib.rs, jumper.rs)#

JumperClamp (a view of a support point, not stored): label (its point's), structure (optional; default the structure of the jumper's from), wire (label of a wire point without a set, held by one string — an I — or two — a V — from structure points), at (0–1 of the jumper's length), clamp_length (m, default 0.1, at most 1). A support's clamp is not a tap; its own weight, ice and wind load the jumper when it has some (the strings' weight and wind are theirs).

A jumper ends at wire points with sets, usually the end points of two sections (a dead-end jumper) or a branch end and a through wire (a tap). It refers to the wire point, not to a section; it takes its defaults from whichever section passes through from.

Electrical systems and circuits (electrical.rs)#

Derived, never stored:

• Conductor paths (conductor_paths): sections joined by jumpers or by sharing an attachment point. A path carries one phase of one system (Line::section_phases); contradicting assignments are errors.
• Circuits (circuits): a conductor path with a direction — its starts are the ends listed in circuit_starts, else it runs along the line from the end that comes first. Circuit { sections, jumpers, starts, ends, chosen, order }; directions gives each section's and jumper's direction in its circuit.
• Potential: a section's nominal voltage and voltage to earth, from which Potential::between gives the voltage between two conductors (used by clearance rules).

Display and criteria#

References and ownership#

How objects point at each other#

Labels are scoped to their structure (or type), span point labels to their section, jumper point labels to their jumper; ids are unique per kind in the line; library ids are unique per library. Span points are the one place a position in a list is a reference: SpanPoint.span (and Stringing::Sag.span, UnstressedLengths.lengths) count the section's spans, so they must change when a structure is added to or taken out of the section's points. A typed structure's sets and labels may come from its type: references to them are checked after Line::resolve.

Ownership and deletion#

A structure owns its points, wire points, strings and stick drawing; a section owns its stringing, span points (with their objects) and spreads; a jumper owns its points (with their objects) and support clamps. Alignment points are their own objects (an alignment lists them); spacers are their own objects between two sections' span points. Everything else is a reference. Deletion goes through the session (crates/ohl-session/src/lib.rs, Command::Delete): when an object takes others with it, the command is refused with the list (SessionError::NeedsConfirmation) unless confirm is set, and then all of it is one log entry, undone together.

Every deletion (and a section's points changed) also takes the circuit_starts no longer a point of a section out of the line settings (starts_follow, a put of meta in the same entry); files written before drop such starts on reading (Line::drop_stale_circuit_starts). A section editor changing a section's points keeps its span points on their spans (Section::set_points, a span found by its two ends), and refuses when a span holding points is gone.

Renames follow references: rename of a structure updates section points, jumper ends and clamps, tied alignment points and circuit_starts; of a section, its spacers and the taps on it; of a jumper, the taps on it; of a route, the alignments, points and structures on it; a rename is a put under the new id and a delete of the old one; rename_attachment (set renumbering) updates the sections, jumpers and circuit starts there; rename_point (a span or jumper point's label) updates its spreads, the spacers on it and the jumpers tapped on it; rename_system updates the sections given it. replace_structure (crates/ohl-session/src/replace.rs) keeps the structure's id, position, orientation, height adjustment, description, routes and fields, and moves the section points, jumper ends and circuit starts at each old set to the new set mapped (given in sets, else the same set when the new structure has it). Library items are not renamed through the session: a changed library id leaves dangling references that Line::resolve / validation report.

Library files#

One directory per kind; TOML with units in the values. Each item has an id of letters, digits, -, _ and .. The app's library editors (crates/ohl-app/src/library.rs, LibraryKind) cover the first five.

Other data files: structure models .ohlfe (ohl-structure-model, version 2: the member kind tension) and poles .ohlp (ohl-pole) next to the .ohls (Structure analysis); clearance rules .ohlr; thermal ambient .ohlta; unit costs .ohlcost; galloping .ohlg; LiDAR class schemes .ohlc; phase distance codes .ohlpd. A project keeps its structure models, poles, clearance rules, ambient cases, unit costs and galloping parameters as library files (below).

Phase distance codes (.ohlpd)#

ohl-phase-distance, version 1: a check plugin's values for the distance between conductors in the span, read and written by the plugin (its layout is the plugin's; a national-code plugin kept outside the repository defines one). OpenOHL only measures (ohl_clearance::phase_distance) and keeps a project's edited copy as a library file of kind phase-distance. The check pairs conductors between the same two structures (and, when asked, nearby conductors elsewhere within a distance) and takes l_k from the strings at their ends (I: its length; V, tension, clamped: 0; the string below a V: its length; a TAK: its suspension string's), and the plugin columns of their sections; the settings (the plugin's choices, station spacing, circuits ticked, nearby pairs and their distance) are not in the file. Results per pair: the worst station (points, where along each conductor, d, the required distance and the plugin's values) and the length of conductor below it; conductors joined by spacers in the span: each one's largest sag between its clamps. A run's parameters keep the plugin's name and version and its choices. See Distance between conductors: the core's part.

Clearance rules (.ohlr)#

Source: crates/ohl-clearance/src/rules.rs (RuleSet, RuleSet::to_toml writes one back). Full reference: Terrain and clearances.

• [[rule]]: a target (LiDAR classes, the ground, other wires), a distance (vertical / radial, fixed or by voltage), the weather cases it applies to, vertical_band (zone width each side of the wire), vertical_depth (the area's depth along the line), voltages (kV of the wires checked; 0: earthed wires) and wires (sections, jumpers or both).
• [wind] (optional): steps, step (Pa), sides — how the desktop clearance windows and ohl zones step the wind up to each case's pressure; ohl line ignores it.
• [check] (optional, CheckScope): circuits (circuit names; empty: every circuit), method (fe / rs: every section solved by it; absent: each section's own), search_distance (m: LiDAR points farther from the wires are ignored) — what the desktop clearance windows and ohl zones solve and read (both through ohl_clearance::zone::run_zone_check); ohl line ignores it.
• The desktop Vertical and Radial clearance windows keep their rules next to the model, in <model>.vertical-clearances.ohlr and <model>.radial-clearances.ohlr (one [[rule]] per row and target kind). A window row (ohl_clearance::zone::ZoneRule) has an optional width of its own (the vertical zone's half width, written as the rule's vertical_band; none: the window's Zone.width); the window's Zone.search is [check] search_distance. Rules refer to LiDAR classes by number (.ohlc schemes) and to weather cases by name.
• Clearance presets of design-code plugins are such rule files, <plugin>-<name>.ohlr among the project's rule files, each with a weather case file of the same name among its weather case files (the cases its rules name); the windows' Load preset… lists them.

Structure type (.ohls)#

Source: crates/ohl-structures/src/structures.rs. All positions in local axes. Full reference: Structure library.

Detail level (StructureType::detail, never stored — an older detail key is read and ignored): 3 full design when model is given or StructureType::missing_for_design finds nothing: there are members, every member has a section and a joint has a support (every extension piece too: its members with sections and a joint with a support; StructureType::members_designed). A joint with only a spring does not count, so a structure standing only on springs stays at level 2. 2 outline when there are members or body polylines that are not all in one plane (within 1 mm, StructureType::body_is_3d); else 1 stick figure. The pole gives its own level (StructureType::pole_detail): a named .ohlp or a [pole] with material, strength and its wall (a thickness, wall = "solid", or a section) 3, a [pole] outline with diameters at two heights 2 (InlinePole::is_3d, InlinePole::missing_for_design); the structure's level is the higher. Checks that depend on the structure's shape must say what they do at each level (Structure detail levels). The finite-element model of the structure's own members is built when its members are designed (members_designed), not when a pole makes the level 3; the pole check runs on a level 3 pole. The meaning of the levels decided for the structure application (capacities derived only at level 3) is in Building structures.

Editing a structure file (apps/structure/ohl-structure-edit, crates): every edit of the structure application and of ohl-app's structure screen is a function on the file's text (toml_edit::DocumentMut, comments and order kept) given the structure as last read; StructureFile keeps the undo and redo of whole edits. Body tools (same crate): generators::generate(t, g) -> Body (joints, members, points put on tips; pure, ids from the inputs), rebuild::{apply, rebuild, rebuild_all, remove_generator, write} (replace only what has the generator's made_by; what something else uses is kept, made by hand, and reported in Report::kept), symmetry::{add_joint, add_member, move_to, removal, make_symmetric} (images matched by position within 1 mm), groups::{groups, set_group, set_group_section, set_group_kind}. StructureFile refuses a file whose [[generator]] or [[symmetry]] tables do not read (body::check). missing(t, level) -> Vec<Missing> lists what the next level lacks (Need::Level: no member, a member without a section — one item per member —, no [[section]], no supported joint (a support; a spring alone does not count); a pole's outline, its material, strength, wall (Place::Pole); an extension member without a section or a piece without a supported joint (Place::Extensions)) and advice (an extension without members at level 3: the FE model leaves it out) (Need::Advice: a point on no joint or member, a joint on one member or none, members crossing within 1 mm away from their ends without a joint); each item names its row (Handle) or its table (Place). It reads the structure only; detail() stays the source of the level. The recipes are edited by place (load_cases, add_load_case, add_load, set_load_case_field, set_load_field, remove_load, remove_load_case; merge_load_cases takes the cases of a .ohlslc text: same name replaces, others are added; store_given_cases writes the line's forces as cases of given values — a value and direction (x, y, -z) per point and non-zero component, line_case, a description starting "Stored from the line" — through it; take_line_load_cases one recipe per line case taking its factored values at every point). The pole (pole: add_outline_row, set_outline_row — refused when the heights would not rise —, remove_outline_row, set_shape, set_field — wall checked as a length or solid —, set_solid / is_solid (wall = "solid", unset only when solid), remove_pole, bring_in a .ohlp's text as a two-height outline from the feet) and the extensions (extension_edits: add_joint — refused outside the piece's heights —, add_member, remove_joint with its members, remove_member, set_field, set_leg, build_piece). geometry_with(t, insulators, extension) gives the joints and members as StructureType::extended makes them (Geometry::extension: the piece's ids) and Geometry::pole the outline's wireframe.

Placed into a line, a type becomes PlacedStrings { points, strings, wires } (global coordinates) that Line::resolve merges with the structure's own items.

Section library (.ohlsec)#

Source: crates/ohl-sections (a core crate: the level 3 checks inside the line read it through ohl-structures-fe), SectionLibrary. Format ohl-sections, version 1 (constants SECTION_FILE_FORMAT, SECTION_FILE_VERSION, SECTION_FILE_EXTENSION). Full reference: Section library.

Shapes: equal_angle, unequal_angle, channel, i_section, rectangular_hollow, circular_hollow, round_bar, polygonal_hollow, general (properties given only). Section::properties() computes area, centroid, second moments about the geometric and principal axes, torsion constant, elastic and plastic moduli, radii of gyration and shear areas; Section::wind_width(direction) the outline's width normal to a wind in the section's plane (body wind from the profiles, decision 10 of Building structures). Several files merge in order (merge: project first, then user; the earlier id wins); missing_materials() lists sections whose material is in none.

Referred to by structures (structure-building §1.3, §4.2): a member's section = "<id>" (of a .ohls full design or an .ohlfe) resolves in the section library first, then in the structure's own [[section]] tables (Model::parse_with, from_structure_type_with, load_with take the SectionLibrary; the plain forms an empty one). A library section becomes ohl_structures_fe::Section::from_library: the profile's area, iy, iz, torsion constant (iy + iz without one), minor principal second moment (i_min, buckling), elastic moduli, and its material's E, G, density and yield; it keeps the profile (Section::profile), which gives the member wind (Model::member_wind, Model::has_profiles; [analysis] drag, default 1). A library id replaces a table of the same id; an id in neither, or a library section's material missing, is refused, naming it. In a project the library is the library kind sections of the project file, per project line (Project file tables); the app reads it with Model::section_library and gives it to the line's structure checks (ohl_loads::capacity::usage_with_sections). Member groups (one section for many members) come later and resolve the same way.

Solving (ohl_structures_fe::solve, analyse): with [analysis] stabilise (default true; Options::stabilise), a solve that fails as a mechanism or unstable is repeated with the joint directions no member stiffens held (ohl_structures_fe::stabilise::Stabilisation: node, translation or rotation, unit direction, a structure axis removed exactly or a spring's stiffness); Solution::stabilised lists them with the force each took (Stabilised), stabilisation_note puts them in words for the usage notes, the structure application's results and ohl structures fe. A stabilisation carrying load (above HELD_SHARE of the loads and HELD_JOINT_SHARE of its joint's) fails as FeError::Held; a remaining mechanism is FeError::Mechanism with the joints that move (joints, moving). Nothing is stored: it is worked out per solve. Solution::reactions (Reaction, force and moment on the structure) has one entry per joint with a support or a spring (Node::is_support): a fixed direction gives the support's force, a sprung one the spring's force −k·u (a direction both fixed and sprung: the support's, the spring carrying nothing), less a stabilisation's share at that joint; Σ reactions balance the loads with the self-weight.

A model member (ohl_structures_fe::Member) carries the file's lk, capacity_tension, capacity_compression (SI, None when not given: the usage computes them as before, check::member_usage) and dead_load_factor (None: Analysis::dead_load_factor, default 1; Model::dead_load_factor(member) gives the one in force, the solver multiplies the member's self-weight by it, Model::weight sums the factored weights — the structure application's load sum —, Model::steel_weight the plain ones); a member's orientation is resolved when the file is read into its reference (model::orientation_reference), so the solver, the member wind and the exports see only reference and roll.

Insulator assembly (.ohli)#

Source: crates/ohl-structures/src/insulators.rs.

Weather and load cases#

WeatherCase (ohl-weather): name (the key other files use), description, tags, temperature (cable), ice_thickness or ice_load, ice_density, wind_pressure, wind_from (right/left, looking ahead), air_density_factor, ambient_temperature.

LoadCase (ohl-loads): name, description, weather (a weather case name), condition (initial, creep, load, max sag), factors vertical, transverse, longitudinal, strength, tags.

Results of ohl_loads::structure_loads (derived, never stored): CaseLoads per load case — case, loads (AttachmentLoad per structure and point), failed (sections and jumpers not solved, in words) and missing (MissingWire: structure, kind WireKind::Section/Jumper, id, reason — one per structure a section not solved ends at or hangs on, or whose strings hold a jumper not solved: that structure's loads in that case are incomplete; CaseLoads::missing_at, is_incomplete). The usage (ohl_loads::capacity, CaseUsage → StructureUsage) carries the same per structure (StructureUsage::missing), marks each Check from such loads incomplete: true, and StructureUsage::status() gives UsageStatus::{NotChecked, Incomplete, Approximate, Pass, Over} — Incomplete whenever a wire is missing, whatever the usage; Approximate (after that) when a check has approximate: true — the FE check of a model whose tension-only members did not settle (ohl_structures_fe::Solution::kept_active: those members kept active as trusses; StructureUsage::is_approximate, approximate_text). The usage CSV (usage_csv, ohl line --usage-csv) ends with an incomplete column: incomplete: section S12 not solved (why); …, then approximate: fe (…) for an approximate check, empty when neither.

Structure load cases ([[load_case]], .ohlslc)#

The structure application's recipes (apps/structure/ohl-structure-loads, crates): in a .ohls as [[load_case]] (the core keeps them as raw tables, StructureType::load_cases), or on their own in a .ohlslc file (format = "ohl-structure-load-cases", version 1). Full reference: Structure load cases.

Evaluated (evaluate) with LineValues (per point: sets, phases; values per line load case, point or set and quantity) into a LoadTable (rows: case, load, at point/member/joint, label, force transverse/longitudinal/vertical down N, source recipe/line/typed, evaluated, missing, note, area — a surface load's member area, m²). Started for a placed structure, the structure application puts the line's forces first (a row per line case and point, source line, no recipe; a line case named as a recipe is "NAME (line)"). The table is a result, not stored in the structure file (the line's cases can be stored as [[load_case]] of given values, above). Typed values (Override: case, load, at, label, force) are kept by the structure application beside the structure file as <stem>.loads.csv (the table's CSV, typed rows only; the structure on its own) or <stem>.<placed structure>.loads.csv (started for a placed structure, --structure; the id with characters other than letters, digits, -, _ as _), written on Save and read on open (ohl_structure_loads::overrides_path). In a project the line application keeps both in the project as library kind loads (beside the structure types in the working folder; only *.loads.csv), so the values typed for a placed structure are stored with it per project line — no field of the line file. A table read back (CSV) types what it has beyond the evaluation (LoadTable::overrides_over). [[load]] is read as case model (joints). CSV of the table (the area column optional when read) and the recipes; XLSX later.

ohl-structure-link fills LineValues from ohl_loads::structure_loads (the six force values; tensions, wire wind and ice not yet), solves table cases on the structure's model (analyse_cases → CaseResult: joints with displacements, members with axial force and usage, reactions, Σ loads and Σ reactions; members' sections from the section library first) and gives the members' areas from the section library (SectionAreas: Model::projected_area — the profile's width for the pressure's direction in the member's y–z plane × length × sin θ; a member whose section is not in the library has no area).

Line-values file (<stem>.<placed structure>.line-values.json beside the structure file, ohl_structure_loads::PlacedValues, JSON, format = "ohl-structure-line-values", version 3; versions 1 and 2 are read too): what the line application hands to the structure application for Edit… on a placed structure — structure (placed structure id), line (project line, or the line file's name), structure_type, cases (the cases the line sends, its structure_loads: the load cases chosen, then the weather cases chosen on their own, weather: <name>), sources (version 2, in the order of cases: load_case or weather_case, ohl_structure_loads::CaseSource; absent in version 1: every case a load case), values (LineValues), others (OtherPlace: the other placed structures of the type with their LineValues; each also with its missing), note (why there are no values: being computed, no load case and no weather case chosen; sections not solved; chosen cases no longer in the line), missing (version 3, absent when empty or in older files: per case the sections and jumpers at this placed structure that did not solve, ohl_structure_loads::MissingWire — case, kind "section" or "jumper", id, reason; filled by ohl_structure_link::missing_wires from CaseLoads::missing; the structure application marks those cases incomplete: PlacedValues::incomplete(case) → incomplete: S12 not solved). Derived data, rewritten when the line changes; never stored in the project.

Structure exports (IFC, SAF, CSV)#

Written by apps/structure/ohl-structure-export (File › Export of the structure application, tool ohl-structure-export); nothing is read back. ohl_structure_link::export_structure turns a level 3 .ohls (through the FE Model), the section library and a LoadTable into plain data, ExportStructure: nodes (id, point, fixed[6], spring[6]), materials (E, G, density, yield), sections (shape from the library or none for a [[section]] table, A, Iy, Iz, It, Wpl, the centroid's offset from the outline box), members (joint and section indices, kind, local axes [x, y, z] as the FE model takes them, length, k, pretension) and load_cases (self_weight factor, loads at a joint, at a point along a member, or uniform per metre along one; structure axes, z up). Formats: IFC4 (members and the structural analysis model), IFC2x3 Coordination View 2.0 (members only, for programs that read that view), SAF 2.2.0 xlsx, CSV tables. Mapping and what is lost: Structure exports.

Where data lives#

Files#

Project file tables (crates/ohl-session)#

Performed checks (ohl_session::reports)#

A check's saved run: a model_object of kind report on the project line it was made on, so it belongs to that line's branch (commits, checkout, merges and bundles carry it like any object; saving, a status, a note, a rename or a deletion is a logged, undoable command). Not part of ohl_line::Line: the line file and the views never see it, and a line replaced (replace_line) keeps it. Restricted edit grants do not limit it. Exported alone as .ohlcr (JSON).

CheckReport (format ohl-check-report, version 1): id (its name, unique on the line), check (e.g. phase-distance), title, time (UTC), user, app (and version), plugin (name and version, when one took part), status (draft, checked, approved), note, state (the line state: line, seq — its last log entry — and objects, a SHA-256 per object kind:id and project library file library:kind/name, compared with now to say what changed since), summary, parameters and results (check-specific JSON). The distance between conductors keeps as parameters the plugin's name and version, the values file's name, text and SHA-256, the plugin's choices, spacing, nearby pairs, the circuits, the weather cases with their values and each circuit's plugin-column values; as results the counts and the pairs below the required distance or within 1 m of it.

Commands (the only way to change a project)#

ohl_session::Command, JSON tagged by op (snake_case): put (kind, id, value as in the line file, ord), delete (kind, id, confirm), move_structure, set_stringing, move_alignment_point, insert_alignment_point (a new point, or an existing point: shared), remove_alignment_point (deletes the point: off every alignment), tie_alignment_point, detach_alignment_point, align_under_structures, delete_structure, delete_attachment (structure, set), replace_structure (id; structure: the new one, its type and extension or its own points, strings and wire points; wires: a typed new structure's wire points as placed, {label, set} — the session does not read the structure library; sets: {from, to} old set → new set, to left out: removed; confirm), rename, rename_attachment, rename_point, rename_system, replace_line, batch. Each is expanded into puts and deletes, the whole line is validated, and the log keeps the command, its inverse, the objects changed and the sections to recalculate. Example (synthetic):

{"op": "batch", "commands": [
  {"op": "move_structure", "id": "T2", "position": [1200.0, 340.0, 455.0]},
  {"op": "set_stringing", "section": "S1",
   "stringing": {"kind": "tension", "horizontal_tension": 18000.0, "temperature": 10.0}}
]}

Where the app reads libraries from (crates/ohl-app/src/model.rs, Sources)#

A project line keeps its libraries as library objects; on opening, kinds it lacks are copied in from these places (one library log entry), and the model reads working copies written to a temporary folder — written again when another project line is chosen with other library files, or a library change is undone or redone. Per-user view settings (ViewPrefs) stay on the computer, never in the project.

The structure application reads a structure's libraries beside its file (Sections/, Insulators/, poles .ohlp, models .ohlfe, recipes .ohlslc, PylonTemplates/) or from the folders the line application passes (the working copy); files it imports there (File › Libraries) are stored into the project by the line application (Change::Libraries). See OHL-Structure.

What a plugin sees#

Plugin tiers and manifests: Writing plugins and ADR-0003. The project's own default values (defaults) and calculation options (solver) are in the line a plugin receives. WebAssembly interface: crates/ohl-plugins/wit/plugin.wit and code.wit (package ohl:plugin@0.1.0; a manifest ohl-plugin.toml targets it with sdk = "0.3"). A WebAssembly plugin never gets Rust structs or the project file: it exchanges text in the file formats above.

So a plugin that writes a line follows the line file rules on this page: global coordinates, ids unique per kind, sections and jumpers ending at wire points with sets, cable / insulator / type naming library ids that exist (or are returned with it, for a project plugin).

Python (ohl module in the application, Python console): ohl.line() gives the working line as a line-file dict; ohl.results(case) the solved spans; ohl.apply(command) / ohl.batch(commands) change the project with the session commands above (validated, logged, undoable). The standalone ohl package (PyPI openohl) (crates/ohl-py) offers unit conversion (convert, quantity_kinds); scripts outside the application read and write the files above.