Export Formats API Reference

Overview

ErgoPlanner supports multiple export formats for project data, calculation results, and documentation. This reference documents the schemas and specifications for each export format.

JSON Project File Format

Project File Schema

ErgoPlanner projects are saved as JSON files with the .ergoplanner extension.

Root Structure

interface ProjectFile {
  /** File format version */
  version: string;
  /** Project metadata */
  metadata: ProjectMetadata;
  /** Flow diagram data */
  flowDiagram: FlowDiagramData;
  /** Simulation settings */
  simulation: SimulationSettings;
  /** Calculation results */
  results?: CalculationResults;
  /** Export timestamp */
  exportedAt: string;  // ISO 8601 date string
}

ProjectMetadata

interface ProjectMetadata {
  /** Project ID (UUID) */
  id: string;
  /** Project name */
  name: string;
  /** Project description */
  description?: string;
  /** Client/owner */
  client?: string;
  /** Project location */
  location?: string;
  /** Design population equivalent */
  populationEquivalent?: number;
  /** Design flow (m³/d) */
  designFlow?: number;
  /** Created timestamp */
  createdAt: string;
  /** Last modified timestamp */
  modifiedAt: string;
  /** Author */
  author?: string;
  /** Project tags */
  tags?: string[];
}

FlowDiagramData

interface FlowDiagramData {
  /** ReactFlow nodes */
  nodes: ReactFlowNode[];
  /** ReactFlow edges */
  edges: ReactFlowEdge[];
  /** Viewport position and zoom */
  viewport?: {
    x: number;
    y: number;
    zoom: number;
  };
}

SimulationSettings

interface SimulationSettings {
  /** Active flow condition */
  activeFlowCondition: FlowConditionType;
  /** Calculation mode */
  calculationMode: CalculationMode;
  /** Temperature (°C) */
  temperature: number;
  /** Controllers */
  controllers?: ControllerConfig[];
  /** Biokinetic model parameters */
  biokineticParameters?: {
    model: 'ASM1' | 'ASM2d' | 'ASM3' | 'ADM1';
    parameters: Record<string, number>;
  };
}

Example

{
  "version": "1.0.0",
  "metadata": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example WWTP Upgrade",
    "description": "Phase 2 capacity upgrade to 100,000 PE",
    "client": "Example Water Authority",
    "location": "Example Town, UK",
    "populationEquivalent": 100000,
    "designFlow": 50000,
    "createdAt": "2024-01-15T10:30:00Z",
    "modifiedAt": "2024-12-30T14:22:00Z",
    "author": "John Smith",
    "tags": ["upgrade", "nitrification", "phase2"]
  },
  "flowDiagram": {
    "nodes": [
      {
        "id": "node-1",
        "type": "processUnit",
        "position": { "x": 100, "y": 100 },
        "data": {
          "label": "Inlet Works",
          "unitType": "influent",
          "parameters": {}
        }
      }
    ],
    "edges": [
      {
        "id": "edge-1",
        "source": "node-1",
        "target": "node-2",
        "data": {
          "streamData": {
            "flow": 50000,
            "tss": 250,
            "cod": 500
          }
        }
      }
    ],
    "viewport": {
      "x": 0,
      "y": 0,
      "zoom": 1
    }
  },
  "simulation": {
    "activeFlowCondition": "DWF",
    "calculationMode": "basic",
    "temperature": 15
  },
  "exportedAt": "2024-12-30T14:22:35Z"
}

---

CSV Export Format

Mass Balance CSV

Mass balance tables are exported as CSV with stream columns and parameter rows.

Column Headers

Parameter, Unit, F1, F2, F3, F4, ...

Standard Rows

Parameter	Unit	Description
Stream Description	-	Stream description text
Source	-	Source process unit
Target	-	Target process unit
Stream Type	-	Stream type classification
Dry weather flow	m³/day	DWF flow rate
Average flow	m³/day	Average daily flow
Max daily flow	m³/day	Maximum daily flow (FFT)
Min instantaneous flow	L/s	Minimum instantaneous flow
Max instantaneous flow	L/s	Maximum instantaneous flow
Peak flow from network	L/s	Peak flow from network model
Suspended solids	kg/day	TSS mass load
BOD	kg/day	BOD mass load
AmmN	kg/day	Ammonia nitrogen mass load
TP	kg/day	Total phosphorus mass load
% DS	%	Percent dry solids (sludge streams)
Avg conc SS	mg/L	Average TSS concentration
Avg conc BOD	mg/L	Average BOD concentration
Avg conc AmmN	mg/L	Average ammonia concentration
Avg conc TP	mg/L	Average TP concentration

Example

Parameter,Unit,F1,F2,F3,F4
Stream Description,-,Raw Influent,Primary Effluent,RAS,Final Effluent
Source,-,Inlet,PST,SST,SST
Target,-,PST,Aeration,Aeration,Outfall
Stream Type,-,mainProcess,mainProcess,recirculation,mainProcess
Dry weather flow,m³/day,50000,50000,50000,50000
Average flow,m³/day,60000,60000,60000,60000
Max daily flow,m³/day,90000,90000,90000,90000
Suspended solids,kg/day,15000,6000,600000,600
BOD,kg/day,12000,7800,0,600
AmmN,kg/day,2700,2700,0,270
TP,kg/day,480,432,0,120
Avg conc SS,mg/L,250,100,10000,10
Avg conc BOD,mg/L,200,130,0,10
Avg conc AmmN,mg/L,45,45,0,4.5
Avg conc TP,mg/L,8,7.2,0,2.0

Process Unit CSV

Process units can be exported with configuration details.

Columns

Column	Description
PU ID	Process unit ID (PU1, PU2, etc.)
PU Number	Process unit number
Name	Process unit name
Type	Process unit type
Quantity	Number of parallel units
Duty Config	Duty/standby configuration
Status	Equipment status (existing/new/to-be-removed)
Volume	Volume (m³)
Area	Area (m²)
Parameters	JSON string of additional parameters

Example

PU ID,PU Number,Name,Type,Quantity,Duty Config,Status,Volume,Area,Parameters
PU1,1,Primary Clarifiers,primaryClarifier,3,2D+1S,existing,,500,"{""depth"": 4.0}"
PU2,2,Aeration Tanks,aerobicZone,4,4D,existing,5000,,"{""doSetpoint"": 2.0}"
PU3,3,Secondary Clarifiers,secondaryClarifier,3,2D+1S,existing,,600,"{""rasRatio"": 1.0}"

---

PDF Report Format

Report Structure

PDF reports are generated with the following standard sections:

Cover Page

• Project name and logo
• Client name
• Report title
• Date
• Revision
• Author

Project Summary

• Project description
• Design parameters (flow, PE, loads)
• Key performance criteria
• Treatment objectives

Process Flow Diagram

• Full-page PFD with stream numbering
• Legend for symbols
• North arrow and scale (if applicable)

Mass Balance Tables

• Stream-by-stream mass balance
• Process unit summary
• Balance verification

Design Calculations

• Process unit sizing
• Equipment specifications
• Performance predictions

Controller Configurations

• Controller setpoints and tuning
• Control strategy description

Appendices

• Assumptions and basis of design
• References
• Calculation worksheets

PDF Generation Parameters

interface PDFExportOptions {
  /** Include cover page */
  includeCover: boolean;
  /** Include process flow diagram */
  includePFD: boolean;
  /** Include mass balance tables */
  includeMassBalance: boolean;
  /** Include design calculations */
  includeCalculations: boolean;
  /** Include controller configs */
  includeControllers: boolean;
  /** Paper size */
  paperSize: 'A4' | 'A3' | 'Letter' | 'Tabloid';
  /** Orientation */
  orientation: 'portrait' | 'landscape';
  /** Include page numbers */
  pageNumbers: boolean;
  /** Include watermark */
  watermark?: string;
  /** Header text */
  header?: string;
  /** Footer text */
  footer?: string;
}

---

DXF Export Format

DXF Structure

Process flow diagrams can be exported to DXF for import into CAD software.

Layers

Layer Name	Description	Color
PROCESS_UNITS	Process unit blocks	7 (white)
STREAMS	Stream connection lines	5 (blue)
LABELS	Text labels	7 (white)
DIMENSIONS	Dimensions and annotations	3 (green)
BORDER	Title block and border	7 (white)

Block Definitions

Each process unit type has a corresponding DXF block:

• PST_BLOCK - Primary clarifier symbol
• AST_BLOCK - Aeration tank symbol
• SST_BLOCK - Secondary clarifier symbol
• PUMP_BLOCK - Pump symbol
• etc.

Attributes

Process units include attributes for:

• PU_NUMBER - Process unit number
• PU_NAME - Process unit name
• FLOW - Design flow rate
• VOLUME - Unit volume
• QUANTITY - Number of units

Example DXF Structure

SECTION
  HEADER
    $ACADVER - DXF version (AC1021 = AutoCAD 2007)
    $INSUNITS - Drawing units (4 = millimeters)
  ENDSEC

SECTION
  TABLES
    TABLE
      LAYER
        0 - Default layer
        PROCESS_UNITS - Process units
        STREAMS - Stream lines
        LABELS - Text labels
      ENDTAB
  ENDSEC

SECTION
  BLOCKS
    BLOCK
      PST_BLOCK
      ... geometric entities ...
    ENDBLK
  ENDSEC

SECTION
  ENTITIES
    INSERT - PST block reference
      ATTRIB - PU_NUMBER = "PU1"
      ATTRIB - PU_NAME = "Primary Clarifier"
    LINE - Stream connection
    TEXT - Label
  ENDSEC

DXF Export Options

interface DXFExportOptions {
  /** DXF version */
  version: 'R12' | 'R14' | 'R2000' | 'R2004' | 'R2007' | 'R2010';
  /** Drawing units */
  units: 'mm' | 'inches' | 'm';
  /** Scale factor */
  scale: number;
  /** Include attributes */
  includeAttributes: boolean;
  /** Include dimensions */
  includeDimensions: boolean;
  /** Layer naming convention */
  layerPrefix?: string;
  /** Export as model space or paper space */
  space: 'model' | 'paper';
}

---

Image Export Format

PNG/SVG Export

Process flow diagrams can be exported as raster (PNG) or vector (SVG) images.

PNG Options

interface PNGExportOptions {
  /** Image width in pixels */
  width: number;
  /** Image height in pixels */
  height: number;
  /** Pixels per inch (resolution) */
  dpi: number;
  /** Background color (hex) */
  backgroundColor: string;
  /** Include transparent background */
  transparent: boolean;
  /** Quality (1-100 for JPEG compression) */
  quality?: number;
}

SVG Options

interface SVGExportOptions {
  /** SVG width */
  width: number;
  /** SVG height */
  height: number;
  /** Include CSS styles inline */
  inlineStyles: boolean;
  /** Embed fonts */
  embedFonts: boolean;
  /** Prettify XML output */
  prettify: boolean;
}

---

Import/Export Service

Planned API

interface ExportService {
  /**
   * Export project to JSON
   */
  exportJSON(project: ProjectData): string;

  /**
   * Export mass balance to CSV
   */
  exportMassBalanceCSV(massBalance: ProcessCalcMassBalance): string;

  /**
   * Export process units to CSV
   */
  exportProcessUnitsCSV(processUnits: ProcessUnitBalance[]): string;

  /**
   * Generate PDF report
   */
  exportPDF(project: ProjectData, options: PDFExportOptions): Promise<Blob>;

  /**
   * Export flow diagram to DXF
   */
  exportDXF(flowDiagram: FlowDiagramData, options: DXFExportOptions): string;

  /**
   * Export flow diagram to image
   */
  exportImage(
    flowDiagram: FlowDiagramData,
    format: 'png' | 'svg',
    options: PNGExportOptions | SVGExportOptions
  ): Promise<Blob>;

  /**
   * Import project from JSON
   */
  importJSON(jsonString: string): ProjectData;

  /**
   * Validate import data
   */
  validateImport(data: unknown): {
    valid: boolean;
    version?: string;
    errors: string[];
    warnings: string[];
  };
}

---

File Extensions

Format	Extension	MIME Type
JSON Project	.ergoplanner	application/json
CSV Mass Balance	.csv	text/csv
PDF Report	.pdf	application/pdf
DXF Drawing	.dxf	application/dxf
PNG Image	.png	image/png
SVG Image	.svg	image/svg+xml

---

Version Compatibility

Version Numbering

ErgoPlanner uses semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Incompatible API changes
• MINOR: Backward-compatible functionality additions
• PATCH: Backward-compatible bug fixes

File Format Versions

File Version	ErgoPlanner Version	Breaking Changes
1.0.0	1.0.0+	Initial format

Migration

When opening files from older versions:

1. Version detection from version field
2. Automatic migration to current format
3. Backup creation before migration
4. Migration log with applied changes

---

Best Practices

JSON Export

• Use JSON.stringify() with 2-space indentation for readability
• Include ISO 8601 timestamps
• Validate against schema before export
• Include version number for future compatibility

CSV Export

• Use UTF-8 encoding with BOM for Excel compatibility
• Quote fields containing commas, quotes, or newlines
• Use consistent decimal separator (period)
• Include units in headers
• Round values appropriately (avoid false precision)

PDF Export

• Embed fonts for consistent rendering
• Use vector graphics where possible
• Include metadata (title, author, keywords)
• Optimize for file size (compress images)

DXF Export

• Use latest compatible DXF version (R2007 recommended)
• Include layer definitions
• Use blocks for repeated symbols
• Add attributes for parametric data
• Test import in target CAD software

---

Related Types

• ProjectMetadata - Project information
• ProcessCalcMassBalance - Mass balance data structure
• FlowDiagramData - Flow diagram nodes and edges