The Calculation System

There is one calculation engine in the platform, and it is available everywhere you annotate. What changes between surfaces is only the packaging — how many pages you get, whether variables flow between pages, and whether you can push a result into a pay item. The math, the units, and the on-screen-equals-PDF guarantee are identical on every surface.

Skill level: Anyone comfortable with a basic formula — no scripting required. Time to read: ~5 minutes.

Writing calculations (works the same everywhere)

Place a calc box (the Calc tool in any annotation toolbar, or Calc ▾ → New math box in the document workspace) and type one statement per line:

``` L := 120 ft W := 12 ft /* deck slab, north span */ Area := L * W Tons := Area * 1.5 in / 12 * 145 / 2000 ```

• Live results as you type; press Enter or tap away to commit a line.
• Units carry through: `12 ft / 3 in` → `48`; areas come out in SF, volumes in CF/CY. Trade shorthands work: LF SF SY CY CF TON PSF KSF EA (upper or lower case).
• Unit conversion: `12 ft to in` → `144 in`.
• `/* … */` adds an inline note; a lone line of text becomes a note automatically.
• Variables from earlier lines (and earlier boxes) are available to later ones. Use one before it's defined and the box says so plainly — "X used before defined — defined on Page N" — never a silent wrong number.
• A box's answer is its last line that computes to a number (reading order).
• Subscripts — type an underscore: `A_n`, `L_total`, `V_1` (full rules in the next section).

Subscripts (A_n) — anywhere you type a name

Type an underscore to make a subscript. The engine treats the whole name as one variable and the display typesets it the way a textbook does:

Where it applies — every place a name is typed:

• Calc boxes: expressions, the name on the left of `:=`, and result labels (`A_n = 12 ft`).
• Calc tables: label cells and the green published as chip show the subscript; the raw text stays raw while you are editing the cell, like Excel.
• Published names: a table cell published as `V_1` is `V_1` in every box that uses it, and prints as V₁.
• PDF exports print exactly what the screen shows.

What does NOT change: the record. The variable is stored and computed as `A_n`; only the typesetting differs, so a subscripted name is still one plain-text token you can search for. Underscores in prose (notes, headings) stay plain underscores.

Where to calc — the four surfaces

1. Standalone: the Calc Document (the document builder)

Project → Tools → Calculations → "New Calc Document" (also on the SOQ → Calculations tab).

The full engineering-document surface: standard 8.5×11 pages (portrait or landscape — standard sizes only), each page a complete annotation canvas (draw, dimension, text, stamps, insert photos, plan sheets, or PDF pages) and a calc surface. Blank pages show the page boundary and printable-margin guide.

• Variables flow through the whole document — define on page 1, use on page 5.
• Project-level record: creating one does NOT create or touch any daily report, and it is never locked by a report's approval.
• Export PDF: the combined multipage document. Values are re-computed server-side by the same engine at export time — the PDF always equals the screen, by construction.
• Your documents appear in the Calc Documents section; older standalone sheets remain below under Calculation Canvases, all still openable.

2. From a pay item in an IDR (the quantity workflow)

Open a pay-item entry → Calc Sheet:

• New Canvas: the scoped linear worksheet linked to that pay item, with Apply to IDR entry.
• New Calc Document: a report-anchored Calc Document — every calc box carries an Apply button labeled with the item code. After applying, the box gains Atlas + Ledger chips and stays editable.

Routing rules on both paths, enforced client- and server-side:

• Numeric standard units (CY, SF, LF, TON, EA…) → write directly to quantity.
• Lump-sum items → confirm as % complete (0–100 enforced).
• Composite items → blocked, with direction to the DMT tab (delivery roll-up owns those quantities).
• Nonstandard units → a confirmation warning first.

Every apply writes an append-only audit row (who, when, previous value, applied value, source line) and stamps the calc sheet onto the entry as provenance.

3. In the document builder from an IDR (Drawings tab)

Any markup set built from the Drawings tab — plan markups, photos, blank sheets — is the same workspace: the Calc ▾ tool is on the toolbar, and calc boxes share variables across that set's pages.

4. On the single-sheet quick annotators

Annotating one photo from the Photos tab, a one-off plan-page markup, or a field sketch — the Calc button is in the annotation toolbar there too, placing live math boxes directly on the image or sheet. Calc is available wherever you annotate.

Templates and reference library

The worksheet's template library (17 DOT calculation templates: HMA tonnage/yield, earthwork average-end-area, rebar takeoff families, drainage, QC, and more) creates a pre-built worksheet you fill in. The reference library inserts standards data — e.g., an ASTM A615 rebar size drops in the bar's diameter/area/weight as defined variables with a citation note.

What's protected for you (the record rules)

• Screen = PDF, always. Exports re-evaluate; nothing stale can be sealed into a legal document.
• Accepted reports lock their calcs. Once a report is accepted, its calc sheets and apply-to-entry writes are locked.
• Applies are audited, never silent. Every write to a pay-item entry has an append-only audit row and provenance back to the exact calc line.
• Atlas + Ledger everywhere. Wherever a pay item appears next to a calc, the spec knowledge (Atlas) and the project record (Ledger) are one tap away.
• Nothing old was migrated or altered. Every pre-existing sheet opens and computes exactly as it did.

Calc tables (2026-08)

A calc table is a grid you type into — rows and columns of raw values and formulas — that lives on a page beside your calc boxes. Cells hold exactly what you typed; every displayed value is computed when the page is read, so a stored number can never drift from what the engine would produce today. A table can publish names into the sheet's variable scope (for example TotalSF), and calc boxes on the same sheet can use them. Tables have the same gear (text size, spacing, background) as calc boxes and export exactly as they appear on screen.

Copying calc boxes and tables between documents

Select a calc box or table and press Ctrl+C (or tap its Copy button), open any other document builder — even in another tab — and press Ctrl+V (or Add page → Paste copied calc box / table). The paste is a copy of the values, not a link: the math is the same, and you are expected to change the inputs for the new situation. Linked (live) calc boxes exist only inside the submittal package builder, on purpose.

Annotating through a calc box (transparent background)

By default a calc box is white "paper". When you need to cloud a number, highlight a line, or point an arrow at a result, open the box's gear and set Background → Transparent. Highlights, clouds, and arrows drawn on the page show through the box, and while any drawing tool is active the boxes let your strokes pass to the page. Switch back to Select to edit the box again. Exports honor the transparent setting.

Display settings: this box, the sheet, everyone

Text size, line spacing, and background can be set per box (the gear). Set for all boxes applies to every box on the document that doesn't have its own settings — a box you adjusted keeps its own until you press Reset. Persisting those document-wide defaults, and company-wide defaults, is planned (proposal #939).

Quick answers

Calc tables — Excel-style fill and corrections (2026-08-26)

• Fill down / across: tap a cell, then drag the blue corner square down or across — the formula copies with its references shifted the way Excel does (B2's =A21.5 becomes =A31.5 on the next row). Values and labels copy as-is.
• Ctrl+D (Cmd+D on iPad keyboards) fills the open cell from the cell above.
• Totals and averages over a range: `=sum(B2:B20)`, `=avg(B2:B20)` (`average` and `mean` are the same function), `=max(...)`, `=min(...)`, `=median(...)`, `=std(...)`. Units carry through: averaging a column of `ft` gives `ft`.
• A fill OVERWRITES every cell it sweeps, empty or not — exactly as Excel does. The blue outline shows the range before you release. Because it overwrites, it is undoable: a "Filled N cells — Undo" chip appears in the footer (Ctrl/Cmd+Z works too). One level, cleared by your next edit, and Undo puts the previous text back exactly as it was.
• Pin a reference with $: =$A$1 never moves when filled; =$A1 pins the column; =A$1 pins the row — exactly as in Excel.
• Subscripts in tables: `V_1` in a label cell or a published name shows as V₁ — see Subscripts (A_n) above.
• Notes that wrap (2026-08-24): a note typed into a cell now wraps onto as many lines as it needs — the row grows to fit, on screen and in the exported PDF alike. Numbers and formulas stay on one line so a column of figures still reads as a column. To change either default, click the cell and tick or untick wrap in the footer bar; the choice is saved with that cell. A cell you set to not wrap shows an ellipsis, and hovering it shows the full text.
• Converting units in a cell: =A1 to cy or the shorthand =A1>cy both convert (A1 must carry a unit, e.g. 27 cf or 27 ft3). $A$1 pins survive a fill.
• Finishing a cell: press Esc, tap ✓ Done, or click anywhere outside the cells (the title, a header, the edge) — your text is kept and the cell closes. While a formula is open, clicking cells still adds them as references; that's how you build a total by pointing.
• Did-you-mean corrections: a mistyped formula (missing =, a misspelled function like smu(, a lowercase cell name, a missing parenthesis) shows a suggestion in the footer with an Apply button. The suggestion is offered, never applied for you — you stay the author of every number.