User Guide · Version 1.0

EarthworkAI User Guide

How to set up a project, run the earthwork, read the results and get plans to the field.

1. Getting started

EarthworkAI turns a project's plan sheets and earthwork tables into quantities, a mass haul plan and field-ready exports. Every project lives in its own folder, so you can copy, back up or hand off a job by copying that folder.

Install

  1. Run EarthworkAI-Setup-1.0.0.exe on Windows 10 or 11. If Windows shows "Windows protected your PC", click More info, then Run anyway.
  2. Click through the installer. Tick Create a desktop shortcut if you want one.
  3. Leave Launch EarthworkAI ticked and click Finish.

The start screen

Choose Create New Project or Open Existing Project. The footer shows Settings and your license status.

Create a project

  1. Click Create New Project.
  2. Type the Project Name, for example 85-0534-267 Roadway. This becomes the folder name.
  3. Fill in Client and Location (they show on reports) and click Create Project.

The project folder gets these subfolders:

FolderWhat goes in it
PlansThe plan set PDFs
SurveySurvey and station data files
SurfacesSurface files
ExportsField plans and CSV exports the app writes
ReportsFinished reports
PhotosSite photos

The default projects folder is Documents\EarthworkAI\Projects. Change it under Settings > Projects folder.

Open a project

Click Open Existing Project and select the folder that holds Project.json. The left-hand Project Explorer opens each page: Dashboard, Construction Plans, Stations, Earthwork, Equipment, Mass Haul, Reports and Project Setup.

2. Project Setup

Project Setup holds the project facts the plans don't hand over cleanly. Fill it in once per project, before running the analysis.

  • Printed select treatment quantity (CY): the bid-tab total, for example 89217.2. The app checks its own result against it.
  • Free haul distance (feet): hauls longer than this count as overhaul. Iowa DOT is 1,000; Kansas DOT is 2,000. Blank means 1,000.
  • Topsoil stockpile station: for example 2260+00. Left blank, stockpile hauls show NOT SET and are flagged for review. Topsoil quantities are read from the bid items; fill them in only to override.
  • Select borrow pit: name and station, for example 2317+00. Leave blank if there is no pit.
  • Station equation: back and ahead stations, only if the project has one.
  • Special Backfill: begin and end stations and thickness. Tick Use instead of select only if it actually replaces select treatment.
  • Select treatment rows: one row per placement range from the plan tabulation.

Click Save. If something is wrong, nothing is saved and a list shows what to fix. Previous versions are kept as .bak files.

3. Project Dashboard

Import the plan PDF first (see Construction Plans), then click RUN EARTHWORK. One run reads the 107-28 tables, calculates cut and fill, builds the internal haul moves, checks contract quantities, plans select treatment and exports the field plan files. The status changes to EARTHWORK READY when it's done.

CheckWhat it tells you
Plan ExtractionEarthwork pages and station rows read, and rows that need a human look
EarthworkTotal cut and fill in CY
Internal HaulNumber of moves, CY hauled and average haul distance
Physical UnmatchedFill with no matching cut and cut with nowhere to go: borrow or waste to review
Contractor Furnished, Class 10 WasteVERIFIED when it matches the bid, REVIEW when it doesn't
2' Select TreatmentOutside select material needed, in CY
Field PlanWhere the field files were saved

RUN PROJECT CHECKS scans the project folder without recalculating and reports READY or REVIEW REQUIRED. OPEN EXPORT FOLDER opens Exports\FieldPlan, which holds files 01_Station_Earthwork.csv through 10_Side_Road_Staking.csv.

4. Construction Plans

  1. Click Import Plans and pick one or more PDFs. They're copied into the project's Plans folder.
  2. Click Analyze Plans to index every page and find the earthwork, quantity, station and cross-section sheets.
  3. Click any plan to view it in the PDF viewer, or Open PDF to open it in your normal PDF program.

5. Stations

Use the Station Manager for projects that don't come from a 107-28 plan set, or to work stations by hand.

  • Import a CSV with columns Station, Cut CY, Fill CY, Material Source, Material Destination, Haul Distance, Notes. Only the station is required.
  • Or click Add Station and type rows in, including common, topsoil, rock and unsuitable CY and shrink/swell %.
  • Calculate Balance updates totals, net and cumulative CY. Save Stations saves them.
  • Generate Haul Plan builds a cut-to-fill plan; Optimize Haul Plan searches for a cheaper set of moves using your equipment.

6. Earthwork and Equipment

Earthwork is a read-only summary of the station quantities and material breakdown. Equipment is where you set up the fleet: click Load Default Fleet for a dozer, a 30 CY scraper and a 30 CY truck, edit them to match your machines, and click Save Equipment. Capacity, utilization, speeds, cycle minutes, hourly and fuel cost, and min/max haul distance drive every production and cost number.

7. Mass Haul

Mass Haul is the full haul plan in tabs, from project control to tomorrow's dispatch sheet. Run Earthwork at least once first. Recalculate reruns the haul optimization after you change Project Setup or Equipment.

Most tabs have filters for Stage, Material and Find. EXPORT SHOWN saves the visible rows to CSV; PRINT SHOWN makes a printable sheet.

Run a day from the Daily Plan tab

  1. Filter to the stage or material the crew is working.
  2. Click VALIDATE PLAN to check the rows.
  3. Print the Daily Dispatch Sheet, Foreman Packet or Tomorrow Plan. Sheets open in your browser, already set up for landscape; print with Ctrl+P.
  4. At day's end, click DAILY COMPLETION LOG to log the released rows. A dated backup of the previous log is kept.

8. Reports and exports

The Reports page shows station earthwork, the optimized haul plan with $/BCY, and the material summary. Export CSV saves it as one file for Excel. BCY is bank (in the ground), LCY is loose (in the truck) and CCY is compacted (in the fill).

The text reports in the project's Reports folder show exactly what the app read from the plans. Check them whenever a number looks off.

9. License and settings

  • A new install runs as a 14-day free trial with every feature unlocked.
  • To activate, go to Settings > Enter License Key, paste the key from your purchase email and click Activate. The start screen footer shows who it's licensed to.
  • The license is re-checked about once a week and works for 30 days without internet.
  • Moving to a new computer: on the old one, click Settings > Remove from this PC, then activate on the new one.
  • Settings > Projects folder sets where new projects are created. Open Log Folder opens the error logs.

10. Troubleshooting

ProblemWhat to do
"Invalid Project Folder"Select the folder that contains Project.json, not a subfolder like Plans
Run Earthwork says no plan PDF was foundImport the plan set under Construction Plans first
EARTHWORK RUN FAILEDRead the error in the table, check the plans imported correctly and try again
Project Setup won't saveFix each item in the list it shows (usually a station or number typo)
A quantity says REVIEWThe app's quantity doesn't match the bid. Check Project Setup and the Reports folder
Haul costs look wrongCheck the Equipment page: Available, Optimize, speeds and hourly costs
License key won't activateCheck your internet connection and that the key matches your purchase email exactly. If it says the key is in use on too many computers, remove it from the old PC or email us
"Something went wrong"Your project files were not changed. Send the newest file from %AppData%\EarthworkAI\logs to vorwald_kory@yahoo.com

Back up your work

A project is just its folder, so copying the folder is a complete backup. Keep a copy on a separate drive and refresh it after each working session.