Construction Takeoff

Construction Takeoff

Convert a set of construction drawings into a bill of quantities: a complete, structured list of the measured quantities a project needs, with every line traceable back to how it was derived. The quantities drive estimated cost, programme, procurement, and contracts — so getting them right, and being honest about confidence, matters more than producing a big number quickly.

The mental model

A takeoff is three steps, and this skill follows them in order. Skipping step 1 is the classic way to produce a fast, wrong takeoff.

1. Work out what to measure. Review the drawings and decide what to measure before counting anything: the list of quantities the scope needs, and which are measured directly versus derived. Work this list against the per-trade coverage checklists in references/trade_checklists/ so a whole category never gets silently dropped — they're the starting-point spine of what a complete BOQ carries for each trade. Keep the breakdown simple — separate items into their own lines only where it genuinely changes the result for this scope.
2. Build the assemblies. For each thing you'll measure, decide what it drives. A measured slab area drives concrete volume, reinforcement, sub-base, and a concrete pump's hours — all by formula. You measure the primary once; the assembly computes the rest.
3. Measure and generate the bill of quantities. Do the counts, lengths, and areas. Because the assemblies are set up, each measurement automatically generates its secondary quantities. Consolidate, and out comes the BOQ.

The principle that makes it work on any trade: AI does judgement, scripts do plumbing

Drawings vary endlessly — by office, country, discipline, and CAD package. The brittle approach is to hardcode rules ("L\d+ is a light, the title block is bottom-right, 1:100 means…"). That breaks on the first set that does it differently, and it silently can't handle a trade nobody added to the list.

So this skill draws a hard line:

• Scripts do the cheap, deterministic work: split the PDF, pull the text layer with exact coordinates, count occurrences of strings they're given, compute polygon areas and polyline lengths at a scale they're given.
• Claude does every piece of judgement: reading the legend and schedules to learn what this set's tags and line-types mean, deciding which quantities are primary, choosing which tokens to count and which regions to exclude, identifying which polygon is the slab, reading the depth off the section, and sanity-checking the result.

The script is never asked what something means. That's why it generalises across all trades without a per-trade rule anywhere in the code.

Run lean

Accuracy first — but most wasted effort is avoidable rendering. Don't render-and-look repeatedly to hunt coordinates: read the schedule/legend region off one overview render, separate plan instances from definitions deterministically (full count − the one-per-mark a schedule defines), and let count --markup-out reuse the hit locations rather than re-finding them. Verify with a single marked-render pass per sheet (full sheet, then zoom a dense zone only if needed) at the lowest legible DPI. Extract text once (the engine already uses the complete words-layer). Spend tokens on judgement and verification, not on exploratory re-rendering.

Field-tested gotchas (read these — each cost a real takeoff)

This skill has been run on real sets; these are the traps that actually bit:

• Tags are usually hyphenated (WC-1, FD-2, AHU-3, D-01). The counter now keeps hyphens inside tags, so pass them exactly as written. If a count returns 0 for every tag but the page has words, it prints a WARNING — never report zeros as "none found" without investigating.
• Rotated A0 sheets: count reports hit x/y in the page's native space. --exclude-bbox is read in render/display space. They do not line up on a rotated sheet. To exclude using the coordinates count just printed, use --exclude-bbox-native. (Or read the exclude box off a render --grid image and use plain --exclude-bbox.)
• Scale is often not a clean 1:N. Title blocks may say "As indicated"; MEP/US sets use imperial scales (1/8"=1'-0"). parse_scale now accepts imperial (pass e.g. --scale "1/8=1'-0" → 1:96), but always verify scale by the grid-spacing regularity check before trusting any area/length.
• The marked PDF must open in Bluebeam. Do NOT deliver a PyMuPDF-saved PDF as the final markup — its rewritten structure fails to open in Bluebeam Revu. See Step 6 for the pikepdf-overlay-on-original method.
• A "folder of discipline PDFs" is often NOT one project. A set handed over as 1. Structural / 2. Plumbing / 3. Architectural / … can be a sampler — each PDF a different building, country and unit system (e.g. an Australian warehouse, a US supermarket, a South-African school). Confirm this in Step 0 and treat each discipline as its own project: quantities are not additive across trades, scales/units differ per PDF, and the deliverable must say so. Don't roll them into one building.
• Area/slab overlays land on the wrong place if the coordinate transform is wrong — this is the single most common markup failure and it bit a real run. A DXF/CAD-exported PDF can carry a page Rotate, a non-trivial content-stream CTM, and a y-axis convention that is not a simple H − y flip. The measured area number can be correct while the shaded box is on the wrong half of the slab. The only defence is the corner-check in Step 6: render the marked page and verify each of the four corners of the shaded rectangle sits on its corner grid bubble before signing off. Never deliver an area overlay you have not corner-checked against the drawing.
• Always deliver the marked PDF as a FILE. Produce it with the pikepdf-overlay method and save it to the output folder. Do not leave markup only "live" in a Bluebeam Revu session — if the tool/workspace goes down, the deliverable is lost. The file is the record.
• Diagrammatic / NTS routing: you can still trace and mark the routes (polyline overlay) to show coverage, but never attach a scaled metre figure — report the run as a derived allowance / fixture-unit estimate and flag it Low. Marking the route ≠ measuring its length. Read the GENERAL NOTES for "diagrammatic" / "schematic" / "not to scale" before trusting any pipe length — MEP plumbing/mechanical sets routinely state "pipe routing shown is diagrammatic" in note 1–3. If they do, every pipe length is an approximation and Low, no matter how cleanly you measured it.
• Monochrome / greyscale CAD exports — you cannot isolate a system by colour. Many Revit/CAD PDFs print every service in greys and black with no colour separation, so the length command's by_stroke colour rollup will NOT separate "all the cold-water line". Then isolate the pipe by line-weight (pipe is drawn heavier than the architectural background — filter strokes to width ≥ ~1.0 and a dark, non-background colour) plus the size label on the run ("1" CW", "4" S") read off the legend — never by colour alone. Say in the notes that the figure was isolated by weight, because that also sweeps in some non-pipe heavy linework (borders, leaders) and widens the band.
• Dashed pipe undercounts its own length. Domestic water / vent / gas are often drawn dashed; length sums only the dash marks, not the gaps, so the raw figure is short by the gap fraction (≈ 40–55%). Read the dash duty-cycle off a zoom (dash vs pitch) and divide by it, or measure a representative solid equivalent run, before reporting. The corrected figure is still Low.
• The same fixture is on the plan AND the risers/part-plans — count it once, on the plan. On plumbing sets a WC/lav/urinal/sink shows on the overall floor plan, again on the enlarged restroom part-plans, and again on the riser diagrams (one fixture, 2–3 appearances). Take fixture counts off the overall floor plan only; treat part-plans/risers as a cross-check, never additive. (Real run: a riser sheet showed WC×8 / LAV×16 against the plan's WC×10 — adding them would have inflated the count.)
• A tagged item's LENGTH may be stated in its schedule — read it, don't scale it. Trench drains, ground beams, counters etc. often carry their run length in the fixture/equipment schedule (e.g. "8 FT (2.44 m)"). The schedule figure is High; a scaled polyline of the same item is Medium at best. Check the schedule's size/length column before measuring any linear.
• A vector PDF can still have NO text layer — "outlined" CAD exports. Many DWG/Revit-to-PDF exports flatten all text to vector outlines (curves), so split_extract reports tens of thousands of vector paths but words = 0 with source_type vector/mixed — it is NOT raster, yet count matches nothing and prints its 0-tags WARNING on every sheet. Don't report "no tags found": recognise the signature (high vector-path count AND words ≈ 0) and either vision-count, or take quantities off the schedules / single-line diagrams instead. You can still read the outlined text off a render (titles, legends, schedules); for landscape content on a portrait sheet, render rotated (often 270°) and crop the table band full-width so a whole row of items is counted in one pass with no left/right seam double-count. Confirm it positively in one line — text-search the page for a tag you can plainly SEE on it (e.g. page.search_for("B2")). If a printed tag returns zero hits, the text is outlined: stop trying to count by text and switch to vision or the schedules. (A schedule sheet on the same set will return real hits — that contrast is the proof.)
• "For Tender" sets often don't contain the quantities at all. Before promising counts, confirm the numbers are actually printed. Schedule Qty columns are frequently blank with a note like "quantities to be confirmed by contractor", and single-line-diagram "No. of points" / "Load" rows are placeholders ("X" / "XX"). If so, the count is simply not in the document — quantify what IS there (circuits by type, cable sizes, equipment types/specs) and say plainly that fitting/outlet counts and cable lengths need a plan symbol count. Never manufacture numbers to fill the column. Surface this in Step 0 so the user can choose to authorise a plan symbol count (the contractor's tender count) before you spend on it.
• Electrical: the single-line diagram (SLD) is a primary counting source — when it's filled in. A DB schedule / SLD lists every final circuit by designation (Lighting / Socket Outlet / Dedicated SSO / Air-conditioning / Geyser …) with its cable size and breaker, so counting circuits by designation off the SLDs is more reliable than symbol-counting the plans and hands you the cable size per circuit for free. Lighting circuits are typically 3×2.5mm² and socket circuits 3×4mm² (verify on the sheet). But heed the placeholder warning above — confirm "No. of points" carries real numbers before treating a circuit count as a fitting count, and remember a circuit count ≠ a fitting/outlet count.
• When you must vision-count, fix the EXTENT of the work FIRST — never count a guessed sub-region. The trap: zoom into the obvious dense cluster, count it, and silently miss a whole wing. Before counting, bound the real extent of the trade's content — take the bounding box of the discipline's own colours straight from the vector geometry (e.g. the red fittings + blue wiring on an electrical plan: walk page.get_drawings(), keep paths whose stroke is that colour, and record min/max x,y), or scan the full sheet at low DPI — then tile the WHOLE of that extent so every zone is covered. A count from a partial region is an undercount, and it won't look wrong until someone checks the markup against the drawing. (Real run: counted the obvious office cluster, missed a boardroom + offices in the lower band → ~40% undercount, only caught when the overlay was finally rendered.)
• Never ship a "zone" rectangle as markup — markup is per item, or nothing. A translucent box drawn around "where I counted" serves no purpose: it proves nothing, can't be checked against individual items, and if its coordinates were eyeballed it visibly won't match the drawing — which destroys trust even when the numbers are fine. Markup means one mark per counted/measured item, driven by the item's own captured location (Step 6), then rendered and verified. If you can't mark per item (a schedule/SLD-only count with no plan coordinates), deliver no overlay and rely on per-line provenance in the workbook. A decorative box is worse than no box.

Composition with related skills

• drawings-analyser — RUN THIS FIRST, every time. This skill's default Step 0 is to hand the whole set to drawings-analyser to break it up: it produces a drawings_analysis/ folder with single-sheet PDFs, per-sheet classifications (type/discipline), a symbol library with crops, the detected scale, a cross-reference graph, and "Answerable / Coordinate hints" — i.e. the scope, scale and tag vocabulary handed to you on a plate. Always run it first (or reuse an existing drawings_analysis/ or 0. AI Context/ folder from a previous run) before any measuring; only fall back to this skill's own lighter split-and-read pass if drawings-analyser is genuinely unavailable. Do NOT use drawings-analyser for the takeoff itself — it understands the set, this skill measures it.
• assemblies — that skill produces a ZZTakeoff import sheet and a human measurement worklist (its rule: a person does the final measuring). This skill is the other path: it does a full AI takeoff, measuring the primaries itself and filling in the quantities. Same primary-vs-secondary backbone, different division of labour. Keep the Excel column names aligned so a user can move between them.
• pdf-markup (optional) — the skill marks up and renders drawings itself (Step 6, via measure.py). If the richer pdf-markup skill happens to be installed, you can use it for fancier annotation, but it is not required.

Reference files (read these at the steps noted)

• references/trade_checklists/ — read at Step 1. One starting-point coverage checklist per trade (structural.md, architectural.md, civil.md, electrical.md, hvac.md, plumbing.md) plus a README.md file-map. Walk the relevant trade's checklist category-by-category so the takeoff doesn't under-extract. Each file lists the primary quantities and ends with a worked assembly showing how one primary expands into its secondaries.
• references/derivation_library.md — read at Step 2 and Step 5. The ratios, waste factors, default depths, and sanity benchmarks that turn each measured primary into its derived secondaries.

Setup

pip install pymupdf pdfplumber Pillow openpyxl pikepdf --break-system-packages
# qpdf is also used for Bluebeam-safe output; install if missing (apt-get install -y qpdf).

Work in a scratch dir and write final deliverables to the user's output folder. Paths are environment-specific — do not assume /mnt/user-data/... or /home/claude/...; use whatever uploads/output locations this session actually provides (in Cowork these are session-scoped). Everything the skill needs — splitting, text/geometry extraction, counting, markup, rendering — is in scripts/. For the Bluebeam-safe marked PDF you also use pikepdf + qpdf (Step 6).

measure.py writes its result as JSON to stdout — redirect or capture it (... > out.json); it does not write a file unless you ask (--markup-out, render --out, markup --out). get_drawings() (used by polygons and length) is the heavy step and can take ~40 s on a big raster sheet, so work one sheet at a time and give it room rather than running the whole set at once.

Workflow

Step 0 — Understand the set, and confirm scope

You cannot take off what you don't understand. Before measuring:

1. Run drawings-analyser FIRST (the default first action). Hand the set to the drawings-analyser skill to break it into single-sheet PDFs and produce per-sheet classifications, a symbol library, the detected scale, and a cross-reference graph (a drawings_analysis/ folder). If a drawings_analysis/, 0. AI Context/, or manifest.json from a previous run already exists, reuse it rather than re-running. Read those artefacts — that is Step 0, and it hands you the scope, scale, and tag vocabulary. Only if drawings-analyser is genuinely unavailable do you run this skill's own lighter split-and-read pass (step 2 below).
2. Fallback split-and-read (only when drawings-analyser is unavailable). Run split_extract.py to get one PDF + one text-layer JSON per sheet (add --render for PNGs you'll want for vision spot-checks):

   python scripts/split_extract.py "/path/to/drawings.pdf" -o ./takeoff/sheets --render
   

   Then, for each sheet, read the JSON and (where useful) the PNG and work out — yourself, not by regex — its drawing type, discipline, and scale. The JSON gives you scale_candidates and source_type. Scale detection is weak in practice — scale_candidates is often empty or ambiguous, and title blocks may read "As indicated". So:

• Read the plan's own scale note (e.g. "SCALE 1:250") off a render, not just the title block.
• Handle imperial scales (1/8"=1'-0" = 1:96, 1/4"=1'-0" = 1:48, 1"=20' = 1:240). Pass them to --scale directly (e.g. --scale "1/8=1'-0") or convert to 1:N.
• Always confirm scale with the grid-spacing regularity check (Step 5): even bay spacings (e.g. 11.5 m × 12) are strong evidence the scale is right; uneven spacings mean it's wrong.
• When the scale is missing or "As indicated", use the scale-calibration ladder in the gotchas above (search every sheet for a printed scale → even grid-bubble spacing → footprint vs known building type). Don't calibrate off noisy dimension-text "chains".
• A raster sheet has no usable vector geometry; lean on the PNG and schedules, and say so.
• Check for an "outlined-text" vector export early. If split_extract (or drawings-analyser) shows a high vector-path count but words ≈ 0 (and source_type is vector/mixed, not raster), the publisher flattened the text to curves — there is no text layer to count, on any sheet. Don't burn time retrying count; decide up front whether to vision-count or to lift quantities from the schedules / single-line diagrams, and tell the user which.

Large MEP PDFs: split_extract can be slow / get killed on big raster-heavy sheets — the kill happens during the rendering of large rasters. If so, don't split the whole set up front: split per page with qpdf and work on demand (e.g. qpdf in.pdf --pages in.pdf N -- pageN.pdf) and run measure.py per sheet. Fixtures/services often live on one plan each (e.g. waste & vent on P100, water on P101) — take each quantity off the sheet it lives on, not every "plan". 3. Learn this set's vocabulary. Read the legend and the schedules (drawings-analyser's symbol library is the head start here). This is what replaces a hardcoded tag dictionary: you find out that on this job L1 is a recessed downlight, L2 is a batten, the dashed red line is the fire main, FW100 labels 100 mm foul water. Note the exact tag strings and line-types you'll later count and measure — and note that legend entries are definitions, not instances. While you're in the schedules, check whether they actually carry quantities (a filled Qty / No.-of-points column) or are blank "to be confirmed by contractor" placeholders — that determines whether a count is even extractable (see the "For Tender" gotcha). 4. Confirm scope with the user. Takeoffs are scoped to a purpose. Ask what trade(s) and which sheets are in play, and what's in or out — unless they've already said. Don't silently take off everything if they wanted just the electrical. If the set turns out to have no text layer and/or no scheduled quantities, raise it here and let the user choose the method (vision count vs schedule/SLD-only vs not feasible) before you spend.

Show the user a short read-back: sheets found, types/disciplines, scales detected, the tag/line vocabulary you've learned, whether quantities are actually present in the document, and the scope you'll work to. Let them correct it before any measuring spend. (You'll turn this into the full coverage list in Step 1, working against the trade checklists.)

Step 1 — Work out what to measure (recommend the primary quantities)

From the understood set and the agreed scope, produce a recommended list of quantities to measure, and present it for confirmation before measuring. For each line give: the element, the measurement type (Count / Linear / Area), the tag or label it corresponds to (from the legend — not a guess), and the sheet(s) it lives on.

Build the list against the trade coverage checklist — this is what stops the takeoff under-extracting. The most common failure of a takeoff is not a wrong number, it's a missing one: the obvious items get measured and a whole category is silently dropped. To prevent that, open the checklist for each in-scope trade in references/trade_checklists/ (see its README.md for the file map: structural.md, architectural.md, civil.md, electrical.md, hvac.md, plumbing.md) and walk every category in it, deciding for this project whether each line is present, absent, or needs splitting. Don't work from memory — open the file; missing a category is the exact error the checklist exists to catch.

These checklists are a starting point, not an exhaustive script. They give a known-good spine of the primary quantities a complete BOQ for that trade usually carries, plus a worked example of how one primary expands into its secondaries. Two things follow:

• Add what the list doesn't have. Every project carries items no generic list anticipates — after walking the checklist, scan the actual drawings and schedules for anything extra and add it.
• Account for what isn't there, don't drop it. A category with nothing on the drawings becomes a one-line "not in scope" note, never a silent omission. That way the read-back proves you considered every category.

Decide what is primary (measured directly) and what is secondary (derived from a primary by formula). The checklist lines are the primaries; everything they drive is a secondary. Measure the minimum set of primaries and let everything else ride on an assembly — fewer measurements means fewer chances to miss something. See references/derivation_library.md for what's conventionally primary vs derivable per trade, and the worked assembly at the foot of each checklist for the expansion pattern.

Land a quantity on every relevant line — even a rough one. If an item is clearly present but impractical to measure precisely, estimate it (off the building footprint, a count × a rate, a perimeter) and flag it Low with the basis in the notes, rather than leaving it blank. A flagged estimate is information the estimator can challenge; a blank is a hole they'll miss. (The one thing you never do is invent a quantity the drawings don't contain — see "Honesty about confidence".)

Keep the breakdown simple. Split one item into two lines only where it genuinely matters for this scope — a type/size/grade that changes the result, a different installation method, or items living on different sheets. Don't split for the sake of it.

Take each quantity off the right type of drawing — this is the single biggest source of double-counting. The same element appears on several sheets: a column is on the plan, the footing plan, and two elevations; a precast panel is on the plan and one elevation; a plumbing fixture is on the floor plan, the enlarged part-plan, and the riser. So:

• Counts come from the plan or the schedule, once — never from elevations, sections, part-plans or risers (those re-show the same items 1–2+ more times; counting there double- or quadruple-counts).
• Elevations/sections are where you get wall/cladding/panel areas (face length × height), member lengths (girt and purlin runs), and heights/levels — not instance counts.
• If the scope spans both, decide per quantity which sheet is its source, and say so. A sheet being in scope doesn't mean every tag on it gets counted.

Present it as: "Here's what I propose to measure directly, off which sheet, and what I'll derive from each. Anything to add or drop?" Wait for sign-off.

Step 2 — Build the assemblies

For each confirmed primary, define the assembly: the secondaries it drives and the formula for each. Read references/derivation_library.md for the standard assemblies, ratios, waste factors, and default depths/thicknesses.

The one rule that never bends: volume is always an area times a depth. You don't measure a volume off a 2D sheet — you measure the area and read the depth/thickness from a section, detail, or schedule, then multiply. Same for trench volumes, footing volumes, asphalt layers.

Record each assembly so Step 4 can apply it mechanically, e.g.:

Primary: Slab on ground — 150mm   (Area, measured)
  ├ Concrete volume   = area × 0.150 × 1.05         m³   (thickness 150mm from S-202 §, 5% waste)
  ├ Reinforcement     = (area × 0.150) × 100        kg   (100 kg/m³, confirm vs structural spec)
  └ Sub-base          = area                        m²
Primary: Slab edge formwork        (Linear, measured separately — perimeter)

Where a material/productivity library and cost codes exist (e.g. via the assemblies skill conventions), reference them so the takeoff carries through to pricing; leave rates blank and flag if no match.

Step 3 — Measure the primaries

Now do the actual measuring, one sheet at a time, working off the durable single-sheet PDFs in sheets/ (or drawings-analyser's drawings_analysis/). The method depends on the measurement type. Everything here is driven by what you learned in Step 0 — you supply the semantics, the script does the geometry.

Counting (tagged items)

Counting is the most reliable measurement, if done off the text layer rather than by eyeballing symbols. You already know the exact tag string for each item (Step 0). Count it:

python scripts/measure.py count "sheets/E-101.pdf" --tags L1 L2 GPO \
    --exclude-bbox 1500 980 1850 1180   # the legend/schedule box — definitions, not instances

• Pass the exact tokens you identified. The script reads the vector text layer in words mode (not span mode — span mode silently drops text held in form XObjects on many CAD exports, which can undercount by 3–5×), and it segments each text run against your vocabulary, so a standalone L1, a jammed L1L2, and L1 inside "L1 RECESSED" all resolve correctly while unrelated runs like SL81 are rejected. It returns a count and the coordinates of every hit. Coordinates are handled in the page's native space, so rotated sheets (very common for A0/A1) are dealt with automatically — including any --bbox/--exclude-bbox you read off a (rotated) render.

• If count returns 0 on every tag of a page that clearly has text, the page almost certainly has no text layer — either a raster scan or an outlined-text vector export (see the gotcha). Verify with split_extract's words/source_type; don't keep retrying tags. Switch to vision counting or to the schedules / single-line diagrams, and flag confidence accordingly.

• Three-way cross-check — this is not optional. A clean count means the text-layer number, the schedule, and the visual all agree:

  1. Text count — what count returns.
  2. Schedule — does it reconcile with the relevant schedule (door schedule row, footing schedule, fixture schedule)?
  3. Vision — mark every hit (Step 6's translucent boxes) and look. If the highlights are sparse against obviously-tagged items, the text layer is incomplete for this sheet — investigate the extraction before trusting the number. If they're dense and complete, you're done. (On a real sheet this is exactly what exposed a 3× undercount: the markup was visibly sparse.) If the three diverge and you can't reconcile them, say so and drop the confidence — don't report a tidy number you don't believe.

• Exclude the FULL schedule, not one row. A schedule often spans many rows (e.g. F1–F13, then DF1, SF1, GB1 lower down) plus typical-detail / note diagrams that contain countable tags (a "FTG DF1" detail will have live DF1 text). A single tight exclude box misses the outliers — they then count as phantom instances. Cover the whole schedule extent AND any note/detail that repeats a tag, then re-verify in Step 6 that no schedule/legend/note cell is highlighted.

• A scheduled tag may be a LINEAR item, not a count. Check the schedule SIZE/LENGTH column: "400 WIDE × 600 DEEP" (a strip footing / ground beam), a trench drain "8 FT (2.44 m)", or a pipe/tray run means the tag labels a length, not an EA — measure it as Linear (or read the stated length straight from the schedule), don't report the label count as a quantity.

• Separate plan instances from definitions. Every mark usually appears once in the schedule (and sometimes in a typical-detail note), and those must not be counted or marked. Exclude those regions with --exclude-bbox (read off one overview render) — this is the mechanism that keeps the count and the markup to real instances, since the markup is driven by the count's locations. Then cross-check the total the deterministic way: full-sheet count minus one per mark the schedule defines (minus any note/detail occurrences) should match. If it doesn't, your exclude region clipped too much or too little — adjust and confirm against the marked render. (Don't try to auto-detect the schedule as a "table" to locate it — on a busy drawing the table finder latches onto the sheet gridlines and returns a page-sized box.)

• Count each resource/installation variant separately (that's why they're separate primaries). Counting from text is reliable; counting from symbols by vision is not — only fall back to a careful vision count when an item genuinely has no text tag, and mark it lower confidence when you do.

Lengths (linear items)

Linear quantities (pipe, cable tray, ductwork, kerb, walls) come from vector geometry at the sheet's scale — but only after you know which lines are the item.

1. Work out what the line means: from the line-type legend and from the text label sitting next to the run (e.g. "FW100", "150 CT"). Extract the actual label — don't infer service or size from line thickness alone.
2. Measure with the scale you confirmed in Step 0:

   python scripts/measure.py length "sheets/H-201.pdf" --bbox 200 200 1400 900 --scale 1:100
   

   This returns every polyline in the region with its length in metres, plus its stroke colour and width, and a by_stroke rollup. Use the stroke (matched to the legend's line-type) and the region to isolate the runs that belong to the item, and sum those.
   • On a greyscale/monochrome export by_stroke colour won't separate systems — isolate by line-weight + the size label instead (see the gotcha). Dashed runs undercount — length sums dashes not gaps; correct by the dash duty-cycle or measure a solid equivalent, and flag Low.
3. Prefer an annotated length where the drawing states one (run measure.py dimensions over the label region) — a called-out "25m" beats a computed polyline. Computed lengths are inherently less certain than counts; reflect that in confidence.

Areas

1. Identify the boundary you want, and what to subtract (the office cut-out inside a warehouse slab; voids; the stair). This is judgement — read the room labels and the plan.
2. Measure:

   python scripts/measure.py polygons "sheets/S-101.pdf" --bbox 80 50 1620 720 --scale 1:100
   

   Returns closed polygons largest-first with area in m². The largest is usually the gross boundary; subtract the cut-outs you identified.
3. For slabs, the grid-extent method is usually the PRIMARY method, not a fallback. Slab edges are almost never a single closed vector polygon — polygons typically returns only small sub-rectangles (a room), never the 10,000 m² floor. So for any slab/floor, go straight to the gridline extents: take the corner grid bubbles, measure the span between them at scale, length × width = footprint, and confirm the bay spacing is even as a scale check. Build the boundary rectangle from the gridLINE positions, not the bubble-circle centroids — on a grid that bubbles only two sides, the centroid bounding box is offset into the margin (this produced a visibly wrong slab overlay until corrected). Deduct cut-outs (office, voids). A stated overall dimension beats both, where it's live text. If pipe/duct routing is annotated "diagrammatic" / "schematic" / NTS (common on plumbing & services plans), do not scale polylines for length — it's fiction. Derive runs from a per-fixture branch allowance or fixture-unit method, or take length only off a coordinated/isometric sheet, and flag the confidence.
4. Validate against the visual — shade the boundary (a translucent box/cloud via Step 6) and confirm it covers what you intended. A returned area far from expectation usually means the bbox clipped the polygon or you grabbed the wrong one; widen or narrow and re-query. Never report an area you haven't eyeballed.

Site sheets — measure earthworks too (don't stop at the structures)

A civil / site sheet is not finished when you've counted the pipes and manholes. The largest-value civil quantities are usually the earthworks, and they are easy to forget because they have no tag — yet "extract every quantity relevant to construction" means they must be on the BOQ. On any site / civil / external-works sheet, always ask for these and measure or estimate them:

• Site clearing & grubbing (m²) — the developed / disturbed platform area. Measure it as a polygon: take the extent of the development (the paved + building + courtyard cluster) off the site plan at the confirmed scale. A density/extent method on the coloured development works well; flag ±, since the cleared area usually runs a little beyond the paving to working margins.
• Topsoil strip (m³) — clearing area × strip depth (150 mm typical if not stated). Note the assumption.
• Bulk cut and fill (m³) — this is the one people skip because it isn't drawn as an object. Derive it from the contours vs the finished levels: read the existing-ground contour range crossing the platform (e.g. 1247–1257) and the finished floor / platform levels (FFL callouts, e.g. ~1251), and estimate an average cut depth and fill depth over the platform; volume = platform area × average depth. Say plainly it is an order-of-magnitude figure and that a proper cut/fill needs a TIN / spot-level model (existing surface vs proposed surface) to firm up — a 2D PDF does not carry the two surfaces. Flag Low, but report a number — a missing earthworks line is a worse error than an approximate one.

Depths (for volumes)

Volume = area × depth. Read the depth/thickness from the section, detail, or schedule — measure.py dimensions over the relevant region, or measure.py tables for a schedule. If it genuinely isn't on the drawings, use a default from references/derivation_library.md and write the assumption into the takeoff. Never bury an assumed thickness.

Tag every measured value with method (text_count / polygon_area / polyline_length / annotated_dimension / schedule / vision_count / estimate) and confidence, and keep its provenance (sheet, scale, region/command). This is what makes the takeoff auditable. Keep the coordinates too — the hit locations from count and the vertices/regions from polygons and length. Step 6 drops them straight onto the drawings as markup.

Write the element ledger as you measure — takeoff/elements.json

The assemblies are the takeoff's derivation layer (primary → secondaries by formula). The ledger is its evidence layer: one machine-checkable file recording everything found, defined, and measured, so Step 5 can verify completeness mechanically instead of by recollection. It costs nearly nothing — count, polygons and length already return every coordinate; the discipline is writing them down in one place as you go, not reconstructing them at the end.

Record three kinds of entry:

• Definitions — every tag the legend or a schedule defines: {tag, kind: "legend_def"|"schedule_def", sheet, schedule_qty (if the column is filled), stated_size_or_length (if any)}.
• Instances — every counted hit: {tag, kind: "instance", sheet, x, y, source: "plan"|"part_plan"|"riser"|"section"}. Only source: "plan" instances are additive; the others exist for cross-checks.
• Measurements — every Linear/Area primary: {item, kind: "length"|"area", value, units, sheet, scale, vertices_or_region, method, confidence}.

The ledger is also what the Step 5 verification agent reads blind — it sees the geometry and definitions, not your narrative or your totals.

Step 4 — Derive the secondaries

Apply each assembly from Step 2 to its measured primary. Concrete = area × thickness × waste; reinforcement = volume × ratio; cable = count × average run × waste; and so on. Round per the assembly. Every secondary inherits its primary's provenance plus the formula used. Derive the FULL set for every primary — Step 7's Takeoff Breakdown must list them all.

Step 5 — Reconcile and sanity-check (do not skip)

A takeoff that hasn't been checked against the rest of the project is a draft, not a deliverable. Step 5 has three passes: a deterministic scope reconciliation over the element ledger (5a), an independent verification agent for every length and area (5b), and the quick judgement checks (5c). See the benchmarks in references/derivation_library.md.

5a — Scope reconciliation over the element ledger (deterministic)

Run these checks over takeoff/elements.json. Each is mechanical — it either passes or it names the exact tag/line that fails. The most common takeoff failure is a missing quantity, and these are the rules that catch it:

1. Legend coverage — every legend_def/schedule_def tag either has plan instances in the ledger or an explicit "not present / not in scope" line in the BOQ. A defined-but-uncounted tag is the missed-wing error in its most catchable form.
2. Schedule vs plan — for every tag with a filled schedule_qty, plan instance count = schedule Qty. Divergence gets reconciled (wrong exclude box, part-plan leak, blank-schedule placeholder) or the line's confidence drops with the discrepancy stated in the notes.
3. Cross-sheet duplicates — every part_plan/riser/section instance of a tag must correspond to a plan instance, never add to the total. If a riser shows more of a fixture than the plan does, investigate before trusting either.
4. Checklist coverage — every category in the in-scope trade checklists maps to a BOQ line or a "not in scope" note. (This re-verifies Step 1's walk after measuring, when it's cheapest to fix.)
5. Assembly completeness — every primary in the ledger has its full set of secondaries derived (cross-check against Step 2's recorded assemblies).

Report the reconciliation result to the user as a short pass/fail table — it is the proof of completeness, and it goes in the workbook's notes.

5b — Indep

…(truncated)