Multi-Aircraft Weight & Balance Calculator

A professional weight and balance calculator designed specifically for flight training and operations. This application provides real-time weight and balance calculations with visual center-of-gravity envelope plotting, PDF report generation, and support for multiple aircraft types.

Overview
Installation
Quick Start
Using the Weight & Balance Calculator
Updating Basic Empty Weight (BEW)
Building a New Aircraft Configuration
Creating Standalone Deployments
Optional: Deploying with a Web Server
Admin Panel
Test Calculations Tool
Command-Line Utilities
Understanding the Calculations
Troubleshooting
Advanced Topics
Contributing
License
Support

Overview

What This Application Does

This weight and balance calculator is a browser-based tool designed for flight training operations. It allows pilots and instructors to:

Calculate weight and balance for multiple aircraft types from a single application
View real-time center-of-gravity positions relative to the aircraft's approved envelope
Generate professional PDF reports for record-keeping and training documentation
Operate in Training mode (with full error feedback) or Checking mode (for student evaluation)
Work completely offline without requiring internet connectivity or a web server

The application performs all calculations using manufacturer-provided data and displays results instantly as you enter flight information. Visual feedback through the CG envelope plot helps you understand whether your loading configuration is within approved limits.

Key Features

Multi-Aircraft Support: Single application supports unlimited aircraft types; currently includes four Citation jet configurations
Real-Time Calculations: Instant feedback as you enter weights, fuel, and passenger information
Visual CG Plotting: Graphical display of center-of-gravity position within the approved envelope
Dual Operating Modes: Training mode shows all errors; Checking mode displays all green for student evaluation
PDF Generation: Professional reports including all flight data, calculations, and CG envelope plot
Offline Capable: Works without internet; includes standalone mode for iPad/mobile devices
Aircraft Builder Tool: Create new aircraft configurations without writing code
Test Framework: Validate calculations against manufacturer data with included test scenarios
Flexible Deployment: Run from local files or deploy on any web server

Supported Aircraft

The application currently includes configurations for:

Cessna Citation CJ1: Light jet with 5-6 seat configuration
Cessna Citation CJ3: Mid-size jet with 6-8 seat configuration
Cessna Citation 560XL: Super mid-size jet with extended capabilities
Cessna Citation 560 Ultra: Ultra-capable mid-size jet configuration

Additional aircraft can be added using the included Aircraft Builder tool (see Building a New Aircraft Configuration).

No Web Server Required

This application is designed to work directly from your file system. You can:

Download the files to your computer
Open index.html directly in your web browser
Use it immediately without any installation or configuration
Copy it to a USB drive and use on any computer
Deploy the standalone version to iPad or mobile devices

While a web server is optional, it can provide benefits for multi-user environments or centralized deployments (see Optional: Deploying with a Web Server).

Installation

Basic Installation

Clone or Download the Repository
```
git clone https://github.com/rjsears/multi-aircraft-web-weight_balance.git
```
Or download the ZIP file from GitHub and extract it to your desired location.
No Additional Software Required

The application runs entirely in your web browser. No installation of additional software is needed for basic use.
For Advanced Features (Optional)

If you plan to use command-line utilities for test generation or building new aircraft configurations, install Node.js:
- Download Node.js from https://nodejs.org/ (LTS version recommended)
- After installation, verify by opening a terminal and running:
```
node --version
npm --version
```

Directory Structure

After installation, your directory structure will look like this:

multi-aircraft-web-weight_balance/
├── index.html                          # Main weight & balance calculator
├── index_standalone.html               # Standalone version (all-in-one file)
├── aircraft_builder.html               # Aircraft configuration builder tool
├── admin.html                          # Admin panel for development and testing
├── test_calculations.html              # Test scenario validation tool
│
├── aircraft/                           # Aircraft configuration directory
│   ├── index.js                        # Aircraft registry (auto-generated)
│   ├── citation560xl.js                # Citation 560XL configuration
│   ├── citation560ultra.js             # Citation 560 Ultra configuration
│   ├── cj1.js                          # Citation CJ1 configuration
│   └── cj3.js                          # Citation CJ3 configuration
│
├── Images/                             # Logo and background images
│   ├── LOFT_logo_130x100.png          # LOFT Flight Deck logo
│   ├── map_background.gif             # Background image
│   ├── Top525b.png                    # Aircraft logos
│   ├── Top525.png
│   ├── Top500.png
│   ├── Top560XL.png
│   └── TopCL350.png
│
├── jspdf.umd.min.js                    # PDF generation library
│
├── generate_tests.js                   # CLI: Generate test scenarios
├── test_math.js                        # CLI: Validate calculations
├── create_standalone.js                # CLI: Create standalone bundle
├── update_aircraft_index.js            # CLI: Update aircraft registry
│
├── package.json                        # NPM configuration
├── LICENSE                             # MIT License
├── README.md                           # This file
└── .gitignore                          # Git exclusions

Installation Verification

To verify your installation is working correctly:

Navigate to the directory where you installed the application
Open index.html in your web browser by:
- Double-clicking the file, or
- Right-clicking and selecting "Open with" your preferred browser, or
- Dragging the file into an open browser window
You should see the weight and balance calculator interface with:
- An aircraft selector dropdown (if multiple aircraft are configured)
- Flight data entry fields
- Weight and balance input sections
- A status display showing four weight cards (ZFW, Ramp, Takeoff, Landing)
- A CG envelope plot

If the interface loads correctly, your installation is complete and working properly.

Quick Start

Opening the Application

Method 1: Direct File Access (Recommended for single users)

Navigate to the installation directory
Double-click index.html
The application opens in your default web browser

Method 2: Browser File Menu

Open your web browser
Use File > Open File (or Ctrl+O / Cmd+O)
Navigate to and select index.html

Method 3: Drag and Drop

Open your web browser
Drag index.html from your file manager into the browser window

Testing with Included Aircraft

Each aircraft configuration includes test scenarios that validate calculations against manufacturer data. To test the application:

Open the Test Calculator
- Navigate to the installation directory
- Open test_calculations.html in your browser
Select an Aircraft
- Use the dropdown menu at the top to select an aircraft (e.g., "Citation CJ3")
- The page will load all test scenarios for that aircraft
Review Test Scenarios
- Each scenario card shows:
  - Scenario name and description
  - Input values (pilot, copilot, passengers, baggage, fuel)
  - Expected results (weights, CG positions, envelope status)
- Scenarios are color-coded:
  - Green: Within approved envelope
  - Red: Outside approved envelope (intentional test cases)
Verify Calculations
- The test calculator automatically runs calculations for each scenario
- Compare displayed results with expected values
- All values should match within acceptable rounding tolerances

If all test scenarios show expected results, your installation is verified and calculations are accurate.

Understanding Training vs Checking Mode

The calculator operates in two modes, selectable via the toggle switch at the top:

Training Mode (Default)

Displays actual status of all weight and CG conditions
Shows errors in red when limits are exceeded
Displays detailed error messages explaining violations
Use this mode for learning, planning, and real flight operations

Checking Mode

Displays all status indicators in green regardless of actual conditions
Hides error messages
Used for evaluating student knowledge and decision-making
Instructor can observe whether student recognizes weight/balance violations

To switch modes, click the "Training / Checking" toggle switch at the top of the calculator.

Using the Weight & Balance Calculator

Selecting an Aircraft

If multiple aircraft are configured (multi-aircraft mode):

Locate the Aircraft Selector
- Dropdown menu appears at the top of the page
- Shows all available aircraft by name
Choose Your Aircraft
- Click the dropdown to see available options
- Select the aircraft you'll be flying
- The page automatically updates with aircraft-specific:
  - Weight limits
  - Station configurations
  - CG envelope
  - Aircraft logo
Aircraft Selection Persistence
- Your selection is remembered between sessions
- When you reload the page, the last-used aircraft is automatically selected

If only one aircraft is configured (single-aircraft mode):

The selector is hidden
That aircraft's configuration is automatically loaded
No selection needed

Entering Flight Data

The calculator is organized into logical sections. Enter data from top to bottom:

Section 1: Flight Data

[Screenshot placeholder: Flight Data section]

Pilot Name: Optional identification field
Copilot Name: Optional identification field
Tail Number: Aircraft registration number (optional)
Departure Airport: Origin airport code (optional)
Destination Airport: Destination airport code (optional)

These fields are for documentation purposes and appear on generated PDF reports but do not affect calculations.

Section 2: Aircraft & Baggage

[Screenshot placeholder: Aircraft & Baggage section]

Basic Empty Weight (BEW): Pre-filled from aircraft configuration
- This is the aircraft's empty weight including standard equipment
- Update if you have a recent weight and balance report (see Updating BEW)
BEW Arm: Pre-filled from aircraft configuration
- Center of gravity location for the empty aircraft (inches from datum)
BEW Moment/100: Pre-filled from aircraft configuration
- Calculated as (BEW × Arm) / 100
Taxi Fuel: Pre-filled with typical taxi fuel amount
- Fuel burned from engine start to takeoff
- Adjust based on airport and taxi conditions
Baggage Compartments: Dynamic fields based on aircraft configuration
- Enter weight in each available baggage compartment
- Fields show maximum weight limits (if specified)
- Calculator warns if limits are exceeded

Section 3: Occupants

[Screenshot placeholder: Occupants section]

Crew Stations: Pilot and copilot positions
- Enter actual weights including headsets and flight gear
Passenger Stations: Individual passenger positions
- Each seat has its own input field
- Stations may have individual weight limits
- Enter weights for all occupied seats; leave empty seats at zero

Section 4: Fuel

[Screenshot placeholder: Fuel section]

Fuel Load: Total fuel on board at engine start
- Enter in pounds (not gallons)
- Maximum fuel load limit is enforced by the calculator
Enroute Burn: Fuel consumed during flight
- Enter estimated fuel burn for the planned flight
- Used to calculate landing weight

Real-Time Calculation

As you enter values, the calculator automatically:

Updates all weight calculations
Recalculates center of gravity positions
Updates the visual envelope plot
Checks all weight and CG limits
Displays warnings if limits are exceeded

There is no "Calculate" button; results update continuously as you type.

Understanding the Status Display

The status display shows four weight conditions that must all be within limits:

[Screenshot placeholder: Status cards display]

Zero Fuel Weight (ZFW)

Aircraft weight with all occupants and cargo, but no fuel
Calculation: BEW + Occupants + Baggage
CG Position: Shows inches from datum and %MAC
Status: Green if within limits, red if exceeded

Ramp Weight

Weight at engine start before taxi
Calculation: ZFW + Fuel Load
CG Position: Includes fuel moment contribution
Status: Green if within limits, red if exceeded

Takeoff Weight

Weight at the moment of takeoff
Calculation: Ramp Weight - Taxi Fuel
CG Position: Updated for taxi fuel burn
Status: Green if within limits, red if exceeded

Landing Weight

Estimated weight at landing
Calculation: Takeoff Weight - Enroute Burn
CG Position: Updated for enroute fuel burn
Status: Green if within limits, red if exceeded

Each card displays:

Weight in pounds
CG position in inches from datum
CG position as %MAC (percent mean aerodynamic chord)
Color-coded status (green = within limits, red = exceeded)

In Training Mode: Colors reflect actual status In Checking Mode: All cards show green regardless of actual status

Reading the CG Envelope Plot

The CG envelope plot provides a visual representation of your aircraft's weight and balance status:

[Screenshot placeholder: CG Envelope plot]

Chart Elements

Horizontal Axis: Center of gravity position (inches from datum)
- Scale also shows %MAC at bottom
Vertical Axis: Aircraft weight (pounds)
Envelope Polygon: The shaded area represents approved CG positions
- Based on manufacturer-approved flight manual data
- Different aircraft have different envelope shapes
Data Points: Four colored dots represent each weight condition
- Blue: Zero Fuel Weight
- Purple: Ramp Weight
- Orange: Takeoff Weight
- Green: Landing Weight

Interpreting the Plot

Points Inside Envelope: Aircraft is within approved limits for that condition
Points Outside Envelope: Aircraft exceeds limits; flight should not be conducted
Points at Envelope Edge: Aircraft is at the limit; exercise caution
Typical Pattern: Points move left (aft CG) as fuel burns during flight

Using the Plot for Planning

Check that all four points are inside the envelope
Verify adequate margin from envelope boundaries
Confirm CG moves in expected direction (usually aft) as fuel burns
Consider how passenger or cargo adjustments would affect CG position

Generating PDF Reports

The calculator can generate professional PDF reports containing all flight data and calculations:

[Screenshot placeholder: Generated PDF report]

Creating a PDF Report

Complete All Calculations
- Enter all flight data
- Verify calculations are correct
- Ensure all required fields are filled
Click "Download PDF"
- Button located at the bottom of the calculator
- PDF generation takes 1-2 seconds
Save or Print
- PDF opens in a new browser tab
- Use browser controls to save or print
- Filename: Weight_Balance_[TailNumber].pdf

PDF Contents

The report includes:

Page 1: Flight Data and Calculations

Aircraft logo and identification
Flight information (pilot, copilot, route)
Aircraft and baggage data
Occupant weights by station
Fuel loading and burn information
Status cards for all four weight conditions
Error messages (if any limits exceeded)
Generation timestamp

Page 2: CG Envelope Plot

Full-size visual representation of CG envelope
All four weight condition points plotted
Axes labeled with weight and CG position
%MAC scale included

Using PDF Reports

Record Keeping: File with flight records or training documentation
Briefing Material: Print for pre-flight briefing
Training Documentation: Include in student training files
Compliance: Demonstrate weight and balance compliance if required

Updating Basic Empty Weight (BEW)

Why Update BEW

Aircraft Basic Empty Weight changes over time due to:

Equipment installations or removals
Modifications and upgrades
Paint or interior changes
Required weight and balance updates per maintenance schedule

The BEW values pre-filled in the calculator are defaults from the aircraft configuration. For accurate calculations, update these values to match your aircraft's current weight and balance report.

How to Update BEW

The BEW can be updated temporarily (for current session only) or permanently (by editing the aircraft configuration file).

Method 1: Temporary Update (Current Session Only)

[Screenshot placeholder: BEW fields with updated values]

Locate the Aircraft & Baggage Section
- Found near the top of the calculator
Update BEW Fields
- Basic Empty Weight: Enter current BEW from aircraft records (pounds)
- BEW Arm: Enter current CG location (inches from datum)
- BEW Moment/100: Enter current moment divided by 100
Verify Calculations Update
- All weight and CG calculations update automatically
- Status cards reflect new BEW values
Note: These changes are temporary
- Values reset to defaults when you reload the page
- Use this method for one-time calculations

Method 2: Permanent Update (Edit Configuration File)

For permanent changes that persist between sessions:

Locate the Aircraft Configuration File
- Navigate to the aircraft/ directory
- Find the file for your aircraft (e.g., cj3.js)

Open in Text Editor

Use any text editor (Notepad, TextEdit, VS Code, etc.)
Find the bewDefaults section:

bewDefaults: {
  weight: 8160,      // Current: 8160 lbs
  arm: 308.41,       // Current: 308.41 inches
  moment: 25166      // Current: 25166 (moment/100)
},

Update Values

Replace the numbers with your current BEW data
Example:

bewDefaults: {
  weight: 8240,      // Updated to 8240 lbs
  arm: 309.15,       // Updated to 309.15 inches
  moment: 25474      // Updated to 25474 (moment/100)
},

Save the File
- Save and close the text editor
Reload the Calculator
- Refresh your browser or reopen index.html
- New BEW values are now the defaults
Verify the Update
- Check that the new values appear in the BEW fields
- Perform a test calculation to ensure accuracy

Testing After BEW Updates

After updating BEW values, verify calculations remain accurate:

Use Known Test Scenarios
- Open test_calculations.html
- Select the aircraft you updated
- Review test scenario results
Compare with Manual Calculations
- Perform a manual weight and balance calculation
- Enter the same values in the calculator
- Verify results match
Check CG Envelope Plot
- Ensure data points plot in expected locations
- Verify envelope boundaries are correct

Building a New Aircraft Configuration

The Aircraft Builder tool allows you to create configurations for new aircraft without writing code. This section provides a complete, step-by-step guide.

Prerequisites

Before building a new aircraft configuration, gather the following information from the aircraft's Flight Manual or Weight and Balance documentation:

Aircraft name and model designation
Basic Empty Weight (BEW), arm, and moment
Maximum weights (Zero Fuel, Ramp, Takeoff, Landing)
Center of gravity envelope data points
Mean Aerodynamic Chord (MAC) specifications (LEMAC and MAC length)
Station locations (crew, passengers, baggage) with arms and weight limits
Fuel moment table (from Weight and Balance section of flight manual)
Aircraft logo image file (PNG format recommended)

Using the Aircraft Builder

[Screenshot placeholder: Aircraft Builder interface]

Open the Aircraft Builder
- Navigate to your installation directory
- Open aircraft_builder.html in your web browser
Complete All Sections
- Follow the steps below in order
- All fields marked "Required" must be completed
- Optional fields can be left empty

Step 1: Basic Information

[Screenshot placeholder: Basic Information section]

Aircraft ID (Required)

Unique identifier for this aircraft
Use lowercase letters and hyphens only
Example: citation-m2, king-air-350, gulfstream-g650
This ID is used in filenames and internal references

Aircraft Name (Required)

Full aircraft name as it appears in documentation
Example: Cessna Citation M2, Beechcraft King Air 350

Page Title (Required)

Title displayed at the top of the calculator page
Example: Citation M2 Weight & Balance Calculator
Can include additional context like "- Training Version"

Logo Filename (Optional)

Filename of aircraft logo image
Example: citation_m2.png
Place the image file in the Images/ directory
If omitted, no logo displays on screen

Logo Base64 (Optional)

Base64-encoded version of logo for PDF reports
Required only if you want logos in PDF exports
To generate:
1. Use an online base64 encoder (search "image to base64")
2. Upload your logo image
3. Copy the complete data URI (includes data:image/png;base64, prefix)
4. Paste into this field

Step 2: Mean Aerodynamic Chord (MAC) Configuration

[Screenshot placeholder: MAC Configuration section]

The MAC is a reference line used to express center of gravity position as a percentage. This data is found in the aircraft's Flight Manual.

LEMAC (Required)

Leading Edge of Mean Aerodynamic Chord
Expressed as inches from the datum
Example: 283.01 (inches)
Found in Flight Manual Section 6 (Weight and Balance)

MAC Length (Required)

Length of the Mean Aerodynamic Chord
Expressed in inches
Example: 74.80 (inches)
Used to calculate %MAC from CG position

Calculation Note: The application calculates %MAC as:

%MAC = ((CG - LEMAC) / MAC_LENGTH) × 100

Step 3: Chart Axes

[Screenshot placeholder: Chart Axes section]

These values define the range of the CG envelope plot. Choose values that encompass the entire CG envelope with some margin.

X-Axis (CG Position)

Min CG (Required)

Minimum CG value for chart horizontal axis
Should be slightly less than the most forward CG envelope point
Expressed in inches from datum
Example: 292 (inches)

Max CG (Required)

Maximum CG value for chart horizontal axis
Should be slightly more than the most aft CG envelope point
Expressed in inches from datum
Example: 306 (inches)

Y-Axis (Weight)

Min Weight (Required)

Minimum weight for chart vertical axis
Should be slightly less than the minimum flight weight
Expressed in pounds
Example: 7000 (pounds)

Max Weight (Required)

Maximum weight for chart vertical axis
Should be slightly more than maximum ramp weight
Expressed in pounds
Example: 15000 (pounds)

Step 4: CG Envelope Definition

[Screenshot placeholder: CG Envelope section]

The CG envelope defines the approved center of gravity positions for different weights. This data comes from the aircraft's Weight and Balance section.

Understanding the Envelope

The envelope is defined as a polygon with multiple points. Each point has:

CG Position: Inches from datum (horizontal position)
Weight: Pounds (vertical position)

Entering Envelope Points

Start with the First Point
- Typically the most forward CG at minimum weight
- Example: [292.5, 7200] = CG 292.5" at 7200 lbs
Add Points in Order
- Click "Add Envelope Point" for each additional point
- Enter points in clockwise or counter-clockwise order
- Trace the envelope boundary completely
Close the Polygon
- The final point should match the first point
- This closes the envelope boundary
- Example: If first point is [292.5, 7200], last point is also [292.5, 7200]

Common Envelope Patterns

Simple Four-Point Envelope (typical for smaller aircraft):

Point 1: [292.5, 7200]   Forward CG at min weight
Point 2: [294.1, 13870]  Forward CG at max weight
Point 3: [304.5, 13870]  Aft CG at max weight
Point 4: [302.9, 7200]   Aft CG at min weight
Point 5: [292.5, 7200]   Close polygon (matches Point 1)

Complex Multi-Point Envelope (typical for larger aircraft):

Point 1: [290.0, 7000]   Forward CG at min weight
Point 2: [292.5, 9000]   Forward CG at intermediate weight
Point 3: [294.1, 12000]  Forward CG at higher weight
Point 4: [295.0, 14000]  Forward CG at max weight
Point 5: [305.0, 14000]  Aft CG at max weight
Point 6: [303.5, 12000]  Aft CG at higher weight
Point 7: [302.0, 9000]   Aft CG at intermediate weight
Point 8: [300.5, 7000]   Aft CG at min weight
Point 9: [290.0, 7000]   Close polygon (matches Point 1)

Verify Your Points
- Ensure points trace a closed boundary
- Check that values match your aircraft's flight manual
- Points should connect to form a complete envelope

Removing Points

If you make an error:

Use the "Remove Point" button next to the incorrect entry
Re-add the correct point
Verify the envelope is still closed

Step 5: Weight Limits

[Screenshot placeholder: Weight Limits section]

Enter maximum weights for each flight phase. These values are found in the aircraft's Limitations section.

Max Zero Fuel Weight (Required)

Maximum weight without fuel
Example: 10510 (pounds)
Found in Section 2 (Limitations) of Flight Manual

Max Ramp Weight (Required)

Maximum weight for ground operations
Includes taxi fuel
Example: 14070 (pounds)
Usually slightly higher than Max Takeoff Weight

Max Takeoff Weight (Required)

Maximum weight at the moment of takeoff
Example: 13870 (pounds)
Critical certification limit

Max Landing Weight (Required)

Maximum weight at landing
Example: 12750 (pounds)
Usually less than Max Takeoff Weight

Min Flight Weight (Optional)

Minimum weight for flight operations
Example: 7000 (pounds)
Leave empty if not specified

Step 6: BEW Defaults

[Screenshot placeholder: BEW Defaults section]

These values represent the aircraft's Basic Empty Weight. Use the most recent weight and balance report for your specific aircraft.

BEW Weight (Required)

Basic Empty Weight of the aircraft
Example: 8160 (pounds)
From aircraft-specific weight and balance report

BEW Arm (Required)

Center of gravity location for empty aircraft
Expressed in inches from datum
Example: 308.41 (inches)
From aircraft-specific weight and balance report

BEW Moment/100 (Required)

Moment divided by 100
Calculation: (BEW Weight × BEW Arm) / 100
Example: 25166
From aircraft-specific weight and balance report
Note: Most weight and balance reports express moments divided by 100

Default Taxi Fuel (Optional)

Typical fuel burned from start to takeoff
Example: 200 (pounds)
Usually 50-300 lbs depending on aircraft size
Leave empty to default to 0

Step 7: Defining Stations

[Screenshot placeholder: Stations section]

Stations are locations where weight can be added (crew, passengers, baggage, cargo). Each station has a specific arm (distance from datum).

Understanding Station Types

crew: Pilot and copilot positions
passenger: Passenger seating positions
baggage: Baggage compartments
storage: Additional storage areas (if equipped)

Adding a Station

Click "Add Station"
Complete the following fields:

Station ID (Required)

Unique identifier for this station
Use lowercase letters and underscores
Examples: pilot, copilot, pax_1, pax_2, forward_baggage, aft_baggage

Station Label (Required)

Display name shown in calculator
Examples: Pilot, Copilot, Passenger 1, Passenger 2, Forward Baggage, Aft Baggage

Arm (Required)

Distance from datum to station center of gravity
Expressed in inches
Example: 282.1 (inches)
From aircraft Weight and Balance documentation

Type (Required)

Select from dropdown: crew, passenger, baggage, storage
Determines how the station is grouped in the calculator

Weight Limit (Optional)

Maximum weight allowed at this station
Example: 500 (pounds for a baggage compartment)
Leave empty if no specific limit applies
Useful for baggage compartments with structural limits

Typical Station Configuration Examples

Small Jet (4 seats + baggage):

Station 1: pilot, "Pilot", 282.1", crew
Station 2: copilot, "Copilot", 282.1", crew
Station 3: pax_1, "Passenger 1", 293.4", passenger
Station 4: pax_2, "Passenger 2", 293.4", passenger
Station 5: baggage, "Aft Baggage", 370.1", baggage, 500 lbs

Mid-Size Jet (6 seats + 2 baggage):

Station 1: pilot, "Pilot", 280.5", crew
Station 2: copilot, "Copilot", 280.5", crew
Station 3: pax_1, "Passenger 1", 295.0", passenger
Station 4: pax_2, "Passenger 2", 295.0", passenger
Station 5: pax_3, "Passenger 3", 310.5", passenger
Station 6: pax_4, "Passenger 4", 310.5", passenger
Station 7: fwd_baggage, "Forward Baggage", 250.0", baggage, 300 lbs
Station 8: aft_baggage, "Aft Baggage", 380.0", baggage, 700 lbs

Removing Stations

Use the "Remove" button next to any station to delete it
Removed stations cannot be recovered; re-add if needed

Step 8: Field Limits

[Screenshot placeholder: Field Limits section]

Field limits are additional constraints on aircraft operations.

Max Fuel Load (Required)

Maximum fuel capacity
Expressed in pounds (not gallons)
Example: 4710 (pounds)
From aircraft Fuel System section or Limitations

Additional Limits (Future Enhancement)

Currently, only fuel load limits are supported. Future versions may include additional field limits.

Step 9: Fuel Moment Table

[Screenshot placeholder: Fuel Moment Table section]

The fuel moment table provides manufacturer data for calculating center of gravity changes as fuel is added or burned. This table is found in the Weight and Balance section of the Flight Manual.

Understanding the Fuel Table

Fuel moments are non-linear because:

Fuel tanks have irregular shapes
CG of fuel changes as tank fills
Multiple tanks may fill at different rates

The table provides specific moment values at different fuel quantities, and the calculator interpolates between these points.

Table Format

Each row contains:

Fuel Quantity: Pounds of fuel
Moment/100: Moment divided by 100 at that fuel quantity

Entering Fuel Table Data

Start with Empty Tanks
- First row: 0 pounds, 0 moment
- This is always the starting point
Add Incremental Data Points
- Click "Add Fuel Point" for each entry
- Copy values from Flight Manual fuel moment table
- Enter in increasing order by fuel quantity

Common Fuel Table Example (CJ3):

Row 1:  Fuel: 0,     Moment: 0
Row 2:  Fuel: 500,   Moment: 620
Row 3:  Fuel: 1000,  Moment: 1240
Row 4:  Fuel: 1500,  Moment: 1860
Row 5:  Fuel: 2000,  Moment: 2480
Row 6:  Fuel: 2500,  Moment: 3100
Row 7:  Fuel: 3000,  Moment: 3720
Row 8:  Fuel: 3500,  Moment: 4340
Row 9:  Fuel: 4000,  Moment: 4960
Row 10: Fuel: 4500,  Moment: 5580
Row 11: Fuel: 4710,  Moment: 5840

End with Full Tanks
- Final row should equal max fuel load
- Example: If max fuel is 4710 lbs, final row is 4710, 5840

Important Notes

Values must be in ascending order by fuel quantity
Use moment/100 values (not full moments)
More data points = more accurate interpolation
Minimum recommended: 5-7 data points
Optimal: 10-15 data points for best accuracy

Removing Fuel Points

Use the "Remove Point" button next to any entry
Cannot remove first point (0, 0)

Step 10: Generate and Download

[Screenshot placeholder: Generate button and success message]

After completing all sections:

Review Your Entries
- Scroll through all sections
- Verify all required fields are completed
- Check for typos or incorrect values
Click "Generate Aircraft Configuration"
- Button located at the bottom of the page
- Validation occurs automatically
Handle Validation Errors
- If required fields are missing, error messages appear
- Red borders highlight problematic fields
- Correct errors and try again
Download the Configuration
- On success, a download prompt appears
- Save the file as: [your-aircraft-id].js
- Example: citation-m2.js
- Note the download location
Success Message
- Confirmation appears on screen
- Instructions for next steps are displayed

Step 11: Installing Your New Aircraft

After generating the configuration file:

Move the Configuration File
- Locate your downloaded .js file
- Move it to the aircraft/ directory
- Example: Move citation-m2.js to /aircraft/citation-m2.js
Add Aircraft Logo (if applicable)
- Place your logo image in the Images/ directory
- Ensure filename matches what you entered in Step 1
- Example: Move citation_m2.png to /Images/citation_m2.png

Update the Aircraft Index

Option A: Using Command Line (Recommended)

npm run update-index

Option B: Manual Update

Open aircraft/index.js in a text editor
Add your aircraft to the array:

window.AIRCRAFT_INDEX = [
  { id: "cj1", name: "Citation CJ1", description: "..." },
  { id: "cj3", name: "Citation CJ3", description: "..." },
  { id: "citation-m2", name: "Citation M2", description: "..." }, // New entry
]

Save the file

Test Your New Aircraft
- Open index.html in your browser
- Select your new aircraft from the dropdown
- Verify:
  - Aircraft name and logo display correctly
  - All stations appear
  - Weight limits are correct
  - CG envelope plots correctly
- Enter test values and verify calculations
Create Test Scenarios (Optional)
- Use the command line to generate test scenarios:
```
npm run generate -- --aircraft citation-m2 --count 20
```
- Validate test scenarios:
```
npm run test -- --aircraft citation-m2
```

Your new aircraft is now fully integrated and ready for use.

Creating Standalone Deployments

What is a Standalone Deployment

The standalone deployment is a single HTML file that contains:

Complete calculator functionality
All aircraft configurations
All required JavaScript libraries
All images embedded as base64

This single file can be:

Downloaded to an iPad or mobile device
Opened directly in Safari, Chrome, or Brave
Used completely offline without any internet connection
Shared via email or file transfer
Stored on a USB drive for portable use

The file is typically 1-2 MB in size and requires no additional files or dependencies.

When to Use Standalone Mode

Use standalone mode when:

Mobile Device Deployment: Installing on iPad or iPhone for in-flight use
Offline Operations: No internet connectivity available
Simplified Distribution: Sending to multiple users via email
Portable Operations: Moving between different computers
Backup Solution: Keeping a self-contained copy for emergencies

Do not use standalone mode when:

Running on a desktop with file system access (use regular index.html)
Deploying on a web server (use regular multi-file version)
Frequently updating aircraft configurations (updates require regenerating standalone file)

Creating the Standalone File

Prerequisites

Node.js must be installed on your computer (see Installation).

Step-by-Step Process

Open Terminal or Command Prompt
- Windows: Press Win+R, type cmd, press Enter
- Mac: Press Cmd+Space, type terminal, press Enter
- Linux: Use your preferred terminal

Navigate to Installation Directory

cd /path/to/multi-aircraft-web-weight_balance

Run the Standalone Generator
```
node create_standalone.js
```

Monitor Progress

Script displays progress messages:

Starting standalone build...
Reading index.html...
Reading jsPDF library...
Reading aircraft index...
Reading aircraft configurations...
Reading images and converting to base64...
Writing index_standalone.html...
Standalone file created successfully!
Size: 1.2 MB

Verify Output
- Check that index_standalone.html exists in your directory
- File size should be 1-2 MB
- Open the file in a browser to test functionality
Test the Standalone File
- Open index_standalone.html in your browser
- Verify all aircraft appear in the dropdown
- Test calculations with each aircraft
- Verify PDF generation works
- Check that all images display correctly

Updating the Standalone File

When you make changes to aircraft configurations or add new aircraft:

Make your changes to files in the aircraft/ directory
Re-run the standalone generator:
```
node create_standalone.js
```
The new index_standalone.html will include all updates
Redistribute the updated file to users

Deploying to iPad or Mobile Devices

Method 1: Email Transfer

Email index_standalone.html to yourself
Open email on your iPad/iPhone
Tap the attachment to download
Tap "Share" icon
Select "Save to Files"
Choose a location (iCloud Drive or On My iPad)
Navigate to the saved file in the Files app
Tap to open in Safari

Method 2: Cloud Storage

Upload index_standalone.html to iCloud Drive, Dropbox, or Google Drive
On your iPad/iPhone, open the cloud storage app
Locate the file
Tap to download and open

Method 3: AirDrop (Mac to iPad)

On your Mac, locate index_standalone.html
Right-click and select "Share" > "AirDrop"
Select your iPad from the list
On iPad, accept the transfer
File appears in Downloads or Files app

Method 4: USB Transfer (Windows/Mac to iPad with iTunes)

Connect iPad to computer via USB
Open iTunes (or Finder on macOS Catalina+)
Select your device
Go to "File Sharing" section
Select Safari or Files app
Drag index_standalone.html into the document list
On iPad, open Files app to access the file

Using the Standalone File on Mobile Devices

Open in Browser
- Tap the file in Files app
- Select "Open with Safari" (recommended) or Chrome
Add to Home Screen (iOS)
- Open the file in Safari
- Tap the Share button
- Select "Add to Home Screen"
- Name it (e.g., "W&B Calculator")
- Icon appears on home screen for quick access
Enable Full-Screen Mode
- After adding to home screen, open from home screen
- Application runs in full-screen mode without browser UI
Offline Use
- Once opened, file works completely offline
- No internet connection required
- All features available

Limitations on Mobile Devices

PDF generation opens in new tab (cannot directly download)
Use "Share" to save or print PDFs
Keyboard input may differ from desktop
Touch targets sized for finger input
Landscape orientation recommended for full view

Optional: Deploying with a Web Server

Why Use a Web Server

While the calculator works perfectly from local files, deploying with a web server provides benefits for multi-user environments:

Benefits of Web Server Deployment

Centralized Access: All users access the same version
Easy Updates: Update once, affects all users immediately
No Local Installation: Users access via URL in their browser
Cross-Platform: Works on any device with a browser
Network Access: Available to anyone on your network
Professional URLs: Use custom domain names

When Web Server Deployment is Recommended

Flight schools with multiple instructors and students
Corporate flight departments with shared resources
Training centers with computer labs
Multi-user office environments
Remote access scenarios

Apache Configuration

If you have an Apache web server:

Copy Files to Web Directory

sudo cp -r /path/to/multi-aircraft-web-weight_balance /var/www/html/weight-balance

Set Permissions

sudo chown -R www-data:www-data /var/www/html/weight-balance
sudo chmod -R 755 /var/www/html/weight-balance

Apache Configuration (optional, for pretty URLs)

Create /etc/apache2/sites-available/weight-balance.conf:

<VirtualHost *:80>
    ServerName weight-balance.yourschool.com
    DocumentRoot /var/www/html/weight-balance

    <Directory /var/www/html/weight-balance>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/weight-balance-error.log
    CustomLog ${APACHE_LOG_DIR}/weight-balance-access.log combined
</VirtualHost>

Enable Site and Restart

sudo a2ensite weight-balance
sudo systemctl reload apache2

Access
- Navigate to http://your-server-ip/weight-balance/
- Or http://weight-balance.yourschool.com if using virtual host

Nginx Configuration

If you have an Nginx web server:

Copy Files to Web Directory

sudo cp -r /path/to/multi-aircraft-web-weight_balance /usr/share/nginx/html/weight-balance

Set Permissions

sudo chown -R nginx:nginx /usr/share/nginx/html/weight-balance
sudo chmod -R 755 /usr/share/nginx/html/weight-balance

Nginx Configuration

Edit /etc/nginx/conf.d/weight-balance.conf:

server {
    listen 80;
    server_name weight-balance.yourschool.com;

    root /usr/share/nginx/html/weight-balance;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Test and Restart

sudo nginx -t
sudo systemctl reload nginx

Access
- Navigate to http://your-server-ip/weight-balance/
- Or http://weight-balance.yourschool.com if using server name

Simple Python Web Server

For quick testing or temporary deployment without installing Apache/Nginx:

Navigate to Application Directory

cd /path/to/multi-aircraft-web-weight_balance

Start Python Web Server

Python 3 (recommended):

python3 -m http.server 8000

Python 2:

python -m SimpleHTTPServer 8000

Access
- Open browser to http://localhost:8000
- Or http://your-computer-ip:8000 from other devices on network
Stop Server
- Press Ctrl+C in terminal

Note: Python's built-in server is for development/testing only. Do not use for production environments.

Node.js Web Server

If you have Node.js installed, use the http-server package:

Install http-server (one-time)
```
npm install -g http-server
```

Navigate to Application Directory

cd /path/to/multi-aircraft-web-weight_balance

Start Server
```
http-server -p 8000
```
Access
- Open browser to http://localhost:8000
- Or http://your-computer-ip:8000 from network
Stop Server
- Press Ctrl+C in terminal

Advanced Options:

http-server -p 8000 -c-1 --cors

-p 8000: Use port 8000
-c-1: Disable caching (useful during development)
--cors: Enable CORS headers

Admin Panel

Accessing the Admin Panel

The admin panel provides a centralized interface for development and testing activities.

[Screenshot placeholder: Admin panel interface]

To Access:

Navigate to your installation directory
Open admin.html in your web browser

Admin Panel Components:

Test scenario generator interface
Quick links to all tools
Documentation and usage instructions
Package script reference

Admin Panel Features

Header Section

LOFT Flight Deck branding
Application title and description

Test Scenario Generator Card

[Screenshot placeholder: Test scenario generator]

Aircraft Selector: Choose which aircraft to generate scenarios for
Scenario Count Input: Specify number of scenarios (20-30 recommended)
Generate Button: Create random, realistic test scenarios
Console Output: Real-time feedback on generation process
Download Button: Save updated aircraft configuration with new scenarios

Quick Access Links

Main Calculator: Opens index.html for flight planning
Aircraft Builder: Opens aircraft_builder.html for creating new aircraft
Test Calculator: Opens test_calculations.html for scenario validation
Math Validator: Instructions for running CLI validation
Documentation: Link to this README
Package Scripts: Reference for available npm commands

Instructions Section

Step-by-step guidance for:

Generating test scenarios
Validating calculations
Building new aircraft
Using command-line tools

Generating Test Scenarios

The admin panel includes a client-side test scenario generator:

Select Aircraft
- Use dropdown to choose target aircraft
- Currently configured aircraft appear in list
Set Scenario Count
- Enter desired number of scenarios
- Recommended: 20-30 scenarios per aircraft
- More scenarios = better test coverage
Click "Generate Scenarios"
- Generator creates realistic, random loading scenarios
- Progress appears in console output
- Generation takes 5-10 seconds
Review Console Output
- Success messages show generated scenarios
- Warnings indicate potential issues
- Errors require correction before proceeding
Download Updated Configuration
- Click "Download Aircraft File"
- Save file with same name as original
- Example: Save as cj3.js
Replace Original File
- Locate the downloaded file
- Move it to the aircraft/ directory
- Replace the existing file
- Test scenarios are now included
Validate New Scenarios
- Open test_calculations.html
- Select the aircraft
- Verify all scenarios display correctly
- Or use CLI: npm run test -- --aircraft cj3

How Test Scenarios Are Generated

The generator creates realistic scenarios by:

Randomly distributing passengers across available seats
Assigning realistic weights (150-220 lbs per person)
Adding baggage to available compartments
Generating fuel loads within aircraft limits
Calculating expected weight and CG values
Ensuring mix of in-envelope and out-of-envelope scenarios
Providing descriptive names and scenarios

Benefits of Test Scenarios

Validate calculator accuracy against known results
Verify envelope containment algorithm works correctly
Test edge cases and limit conditions
Provide realistic examples for training
Automate regression testing after changes

Test Calculations Tool

Purpose of Test Calculations

The test calculations tool (test_calculations.html) validates that the calculator produces correct results by comparing calculated values against expected values from test scenarios.

[Screenshot placeholder: Test calculations interface]

Key Uses:

Validation: Ensure calculations match manufacturer data
Regression Testing: Verify updates don't break existing functionality
Training Examples: Show students various loading scenarios
Visual Verification: See CG envelope plots for each scenario

Using the Test Calculator

Open the Test Calculator
- Navigate to your installation directory
- Open test_calculations.html in browser
Select an Aircraft

[Screenshot placeholder: Aircraft selector]
- Use the dropdown at the top
- Choose the aircraft you want to test
- Page loads all test scenarios for that aircraft
Review Scenario List

[Screenshot placeholder: Scenario list]

Each scenario card displays:
- Scenario Name: Descriptive identifier
- Description: What the scenario tests
- Status Indicator: Green (pass) or Red (fail)
Expand a Scenario

[Screenshot placeholder: Expanded scenario]

Click any scenario to view details:
- Input Section:
  - Pilot/copilot weights
  - Passenger weights by position
  - Baggage weights by compartment
  - Fuel load and burn values
- Expected Results:
  - Zero Fuel Weight
  - Ramp Weight
  - Takeoff Weight
  - Landing Weight
  - CG positions (inches and %MAC)
  - Envelope status (in/out)
- Calculated Results:
  - Live calculations from same algorithm as main calculator
  - Color-coded comparison with expected values
  - Difference displayed if values don't match
- CG Envelope Plot:
  - Visual representation of scenario
  - Shows where each weight condition plots
  - Envelope boundary displayed
  - Points colored by status
Verify Each Scenario
- Calculated values should match expected values
- Small differences (<0.1%) are acceptable due to rounding
- Large discrepancies indicate calculation errors
Summary Statistics

[Screenshot placeholder: Summary section]

At the bottom of the page:
- Total Scenarios: Count of all test cases
- Passed: Scenarios where calculated matches expected
- Failed: Scenarios with discrepancies
- Pass Rate: Percentage of successful validations

Understanding Test Results

Green Status (Pass)

Calculated weight within 1 lb of expected
Calculated CG within 0.1 inch of expected
Envelope status matches expected (in/out)
Scenario validates successfully

Red Status (Fail)

Weight difference > 1 lb
CG difference > 0.1 inch
Envelope status mismatch
Indicates calculation error or incorrect expected values

Common Failure Causes

Rounding Differences: Minor variations in rounding can cause small differences
- Solution: Update expected values if difference is <0.1%
Incorrect Expected Values: Test scenario has wrong expected data
- Solution: Regenerate scenarios or manually correct expected values
Calculation Error: Algorithm produces wrong results
- Solution: Review calculation logic, check fuel moment interpolation
Configuration Error: Aircraft configuration has incorrect data
- Solution: Verify station arms, fuel table, and envelope points

Using Test Results for Debugging

If scenarios fail:

Check Configuration Files
- Verify station arms are correct
- Check fuel moment table data
- Confirm envelope points match flight manual
Manual Calculation
- Perform hand calculation for failing scenario
- Compare with calculator results
- Identify where divergence occurs
Inspect Console
- Open browser developer tools (F12)
- Check console for error messages
- Look for calculation warnings
Compare with Known-Good Results
- Use manufacturer-provided examples
- Verify results match official documentation

Command-Line Utilities

The application includes Node.js command-line utilities for advanced operations. These tools are optional but provide powerful functionality for development and testing.

Prerequisites for CLI Tools

Node.js Installation
- Download from https://nodejs.org/
- Install LTS version
- Verify installation:
```
node --version
npm --version
```
No Additional Dependencies
- Scripts use only Node.js built-in modules
- No npm install required
Terminal Access
- Windows: Command Prompt or PowerShell
- Mac: Terminal
- Linux: Any terminal emulator

Generating Test Scenarios (CLI)

The CLI test generator creates realistic random scenarios for validation.

Command Syntax:

node generate_tests.js [--aircraft <id>] [--count <number>]

Parameters:

--aircraft: Aircraft ID (optional, prompts if omitted)
--count: Number of scenarios to generate (optional, prompts if omitted)

Usage Examples:

Interactive Mode (prompts for inputs):

node generate_tests.js

Output:

Available aircraft:
  1. citation560xl - Citation 560XL
  2. citation560ultra - Citation CE560 Ultra
  3. cj1 - Citation CJ1
  4. cj3 - Citation CJ3

Select aircraft (1-4): 4
How many scenarios? (recommended 20-30): 25

Generating 25 scenarios for Citation CJ3...
✓ Scenario 1: Light Load - Forward CG
✓ Scenario 2: Full Passenger - Aft CG
...
✓ Scenario 25: Maximum Takeoff Weight

Backup saved to aircraft/backups/cj3_backup_20241117_143052.js
Updated aircraft/cj3.js with 25 new scenarios

Command-Line Mode (all parameters specified):

node generate_tests.js --aircraft cj3 --count 30

Using NPM Scripts (recommended):

npm run generate:cj3              # Generate 20 scenarios for CJ3
npm run generate:cj3-large        # Generate 50 scenarios for CJ3
npm run generate:cj1              # Generate 20 scenarios for CJ1
npm run generate:citation560xl    # Generate 20 scenarios for 560XL

What Happens During Generation:

Loads aircraft configuration
Creates backup of existing file (in aircraft/backups/)
Generates random scenarios:
- Realistic passenger distributions
- Varied baggage loading
- Different fuel loads
- Mix of in-envelope and out-of-envelope cases
Calculates expected results for each scenario
Updates aircraft configuration file with new scenarios
Saves to aircraft/[aircraft-id].js

Backup Files:

Automatically created before each generation
Stored in aircraft/backups/ directory
Named with timestamp: cj3_backup_20241117_143052.js
Restore if needed by copying back to aircraft/ directory

Validating Calculations (CLI)

The CLI validator runs all test scenarios and reports pass/fail results.

Command Syntax:

node test_math.js [--aircraft <id>]

Parameters:

--aircraft: Aircraft ID (optional, prompts if omitted)

Usage Examples:

Interactive Mode:

node test_math.js

Output:

Available aircraft:
  1. citation560xl - Citation 560XL
  2. citation560ultra - Citation CE560 Ultra
  3. cj1 - Citation CJ1
  4. cj3 - Citation CJ3

Select aircraft (1-4): 4

Running tests for Citation CJ3...

✓ Scenario 1: Light Load - Forward CG
  ZFW: Expected 8500, Got 8500 (PASS)
  CG: Expected 294.5, Got 294.5 (PASS)

✓ Scenario 2: Full Passenger - Aft CG
  ZFW: Expected 10200, Got 10200 (PASS)
  CG: Expected 302.8, Got 302.8 (PASS)

...

✗ Scenario 15: Maximum Baggage
  ZFW: Expected 9850, Got 9852 (FAIL - difference: 2 lbs)
  CG: Expected 298.3, Got 298.4 (FAIL - difference: 0.1 in)

═══════════════════════════════════════
Test Results: 24/25 passed (96%)
1 scenario requires attention
═══════════════════════════════════════

Command-Line Mode:

node test_math.js --aircraft cj3

Using NPM Scripts (recommended):

npm run test                  # Prompts for aircraft
npm run test:cj3              # Test CJ3
npm run test:cj1              # Test CJ1
npm run test:citation560xl    # Test Citation 560XL

Validation Criteria:

A scenario passes if:

All weights match within 1 lb
All CG positions match within 0.1 inch
All %MAC values match within 0.1%
Envelope status matches (in/out)

Interpreting Results:

All Pass: Calculations are accurate, aircraft is ready for use
Minor Failures (<5%): May be acceptable rounding differences
- Review failed scenarios
- Update expected values if differences are negligible
Major Failures (>5%): Indicates calculation or configuration errors
- Review aircraft configuration
- Check fuel moment table
- Verify station arms
- Manually recalculate failed scenarios

Updating Aircraft Index

The aircraft index registry (aircraft/index.js) must be updated when adding new aircraft.

Command Syntax:

node update_aircraft_index.js

When to Use:

After creating a new aircraft configuration
After renaming an aircraft file
After removing an aircraft
When aircraft list seems out of sync

Usage:

node update_aircraft_index.js

Output:

Scanning aircraft directory...

Found aircraft configurations:
  ✓ citation560xl.js
  ✓ citation560ultra.js
  ✓ cj1.js
  ✓ cj3.js
  ✓ citation-m2.js (new)

Updating aircraft/index.js...
✓ Index updated successfully
5 aircraft registered

Using NPM Scripts:

npm run update-index

What It Does:

Scans aircraft/ directory for all .js files
Reads each file to extract aircraft metadata
Generates aircraft/index.js with complete registry
Sorts aircraft alphabetically by name
Preserves all aircraft descriptions

Manual Verification:

After running, open aircraft/index.js to verify:

window.AIRCRAFT_INDEX = [
  {
    id: "citation560ultra",
    name: "Citation CE560 Ultra",
    description: "Ultra-capable mid-size jet"
  },
  {
    id: "citation560xl",
    name: "Citation 560XL",
    description: "Super mid-size jet"
  },
  {
    id: "cj1",
    name: "Citation CJ1",
    description: "Light jet configuration"
  },
  {
    id: "cj3",
    name: "Citation CJ3",
    description: "Mid-size jet"
  },
  {
    id: "citation-m2",
    name: "Citation M2",
    description: "New aircraft configuration"
  }
]

Creating Standalone Files (CLI)

Generate the standalone single-file version for offline use.

Command Syntax:

node create_standalone.js

Usage:

node create_standalone.js

Output:

Starting standalone build...

✓ Reading index.html... (142 KB)
✓ Reading jsPDF library... (397 KB)
✓ Reading aircraft index... (1 KB)
✓ Reading aircraft configurations...
  ✓ citation560xl.js (45 KB)
  ✓ citation560ultra.js (48 KB)
  ✓ cj1.js (42 KB)
  ✓ cj3.js (51 KB)
✓ Reading and converting images to base64...
  ✓ LOFT_logo_130x100.png (15 KB)
  ✓ map_background.gif (8 KB)
  ✓ Top525b.png (22 KB)
  ✓ Top525.png (20 KB)
  ✓ Top500.png (19 KB)
  ✓ Top560XL.png (24 KB)
  ✓ TopCL350.png (21 KB)

✓ Writing index_standalone.html... (1.2 MB)

═══════════════════════════════════════
Standalone file created successfully!

Output: index_standalone.html
Size: 1.2 MB
═══════════════════════════════════════

Test by opening index_standalone.html in your browser
Deploy to iPad by emailing or using AirDrop

What It Does:

Reads main index.html file
Inlines jsPDF library code
Embeds all aircraft configurations
Converts all images to base64 data URIs
Removes external script references
Creates self-contained index_standalone.html

Result:

Single HTML file: index_standalone.html
Size: 1-2 MB
Contains everything needed to run
No external dependencies
Works completely offline

When to Regenerate:

After updating aircraft configurations
After adding new aircraft
After changing images
Before deploying to mobile devices

Understanding the Calculations

This section explains how the calculator performs weight and balance calculations. Understanding these methods helps validate results and troubleshoot issues.

Weight and Balance Method

The calculator uses the moment method for all calculations. This is the standard method used in aviation weight and balance.

Basic Formula:

Moment = Weight × Arm

Where:

Weight: Mass in pounds
Arm: Distance from datum in inches
Moment: Weight × Distance (expressed as Moment/100)

Why Divide by 100?

Moments are large numbers (e.g., 8160 lbs × 308.41 inches = 2,516,626). To simplify calculations and reduce errors, the aviation industry uses "Moment/100":

Moment/100 = (Weight × Arm) / 100
Example: (8160 × 308.41) / 100 = 25,166

All calculations in this application use Moment/100.

Center of Gravity (CG) Calculation

Center of gravity is the balance point of the aircraft.

Formula:

CG = (Total Moment / Total Weight) × 100

Step-by-Step Example (CJ3):

Basic Empty Weight (BEW):
- Weight: 8160 lbs
- Arm: 308.41 inches
- Moment/100: 25,166
Add Pilot (282.1 inch arm):
- Weight: 200 lbs
- Moment/100: (200 × 282.1) / 100 = 564
Add Copilot (282.1 inch arm):
- Weight: 180 lbs
- Moment/100: (180 × 282.1) / 100 = 508
Add Passenger 1 (293.4 inch arm):
- Weight: 170 lbs
- Moment/100: (170 × 293.4) / 100 = 499
Total Before Fuel:
- Weight: 8160 + 200 + 180 + 170 = 8,710 lbs
- Moment/100: 25,166 + 564 + 508 + 499 = 26,737
Calculate CG:
- CG = (26,737 / 8,710) × 100 = 307.0 inches
Add Fuel (2000 lbs, moment from fuel table):
- Fuel Moment/100: 2480 (interpolated from table)
- Total Weight: 8710 + 2000 = 10,710 lbs
- Total Moment/100: 26,737 + 2480 = 29,217
- CG = (29,217 / 10,710) × 100 = 272.8 inches

Percent Mean Aerodynamic Chord (%MAC)

Many aircraft express CG limits as a percentage of the Mean Aerodynamic Chord (MAC).

Formula:

%MAC = ((CG - LEMAC) / MAC_LENGTH) × 100

Where:

CG: Center of gravity in inches from datum
LEMAC: Leading Edge of MAC in inches from datum
MAC_LENGTH: Length of MAC in inches

Example (CJ3):

CG: 300.0 inches
LEMAC: 283.01 inches
MAC_LENGTH: 74.80 inches

%MAC = ((300.0 - 283.01) / 74.80) × 100
%MAC = (16.99 / 74.80) × 100
%MAC = 22.7%

Typical %MAC Ranges:

Forward Limit: 8-15% MAC
Aft Limit: 35-45% MAC
Normal Operations: 15-30% MAC

Fuel Moment Interpolation

Fuel moments are non-linear due to irregular tank shapes. The calculator uses linear interpolation between table values.

Fuel Moment Table Example (CJ3):

Fuel (lbs)  | Moment/100
------------|------------
0           | 0
500         | 620
1000        | 1240
1500        | 1860
2000        | 2480
2500        | 3100
3000        | 3720
3500        | 4340
4000        | 4960
4500        | 5580
4710        | 5840

Interpolation Formula:

moment = moment_low + ((fuel - fuel_low) / (fuel_high - fuel_low)) × (moment_high - moment_low)

Example: Find moment for 1750 lbs of fuel

Find Surrounding Values:
- fuel_low = 1500 lbs, moment_low = 1860
- fuel_high = 2000 lbs, moment_high = 2480

Calculate:

moment = 1860 + ((1750 - 1500) / (2000 - 1500)) × (2480 - 1860)
moment = 1860 + (250 / 500) × 620
moment = 1860 + 0.5 × 620
moment = 1860 + 310
moment = 2170

Result: 1750 lbs of fuel = 2170 moment/100

Why Interpolation Matters:

Fuel CG changes as tanks fill
Wing tanks fill outboard then inboard
Auxiliary tanks affect CG differently
Accurate interpolation ensures correct CG calculations

Envelope Containment

The calculator determines if a CG point is inside the approved envelope using a ray casting algorithm.

How It Works:

Define Envelope as Polygon: Array of [CG, Weight] points
Cast Ray: Draw imaginary horizontal line from test point to infinity
Count Intersections: Count how many envelope edges the ray crosses
Determine Status:
- Odd number of intersections: Point is INSIDE envelope
- Even number of intersections: Point is OUTSIDE envelope

Example (CJ3 Envelope):

Envelope Points:

[292.5, 7200]  → [294.1, 8500]  → [294.1, 13870] →
[304.5, 13870] → [302.9, 7200]  → [292.5, 7200]

Test Point: [298.0, 10000]

Cast ray from [298.0, 10000] to the right
Count intersections with envelope edges
Ray intersects 1 edge (right side of envelope)
Odd number: Point is INSIDE envelope
Result: This loading is approved

Edge Cases:

Point on Boundary: Considered inside (conservative approach)
Point at Vertex: Special handling to avoid double-counting
Vertical Edges: Handled correctly by algorithm

Visual Representation:

The CG envelope plot shows:

Green area: Approved envelope
Colored dots: Weight conditions
Dots inside green: Approved
Dots outside green: Exceeds limits

Troubleshooting

Application Won't Load

Symptom: Opening index.html shows a blank page or error message

Possible Causes and Solutions:

JavaScript Disabled in Browser
- Check browser settings
- Enable JavaScript
- Try a different browser
File Path Issues
- Verify all files are in correct locations
- Check that aircraft/ directory exists
- Ensure jspdf.umd.min.js is present
Browser Compatibility
- Use modern browser: Chrome, Firefox, Safari, Edge
- Update browser to latest version
- Avoid Internet Explorer (not supported)
Browser Console Errors
- Press F12 to open Developer Tools
- Check Console tab for error messages
- Look for missing file errors
- Verify paths are correct
Local File Restrictions (Less Common)
- Some browsers restrict local file access
- Try loading from a web server instead
- Or use standalone version

Aircraft Not Appearing

Symptom: Aircraft selector is empty or missing expected aircraft

Possible Causes and Solutions:

Aircraft Index Not Updated
- Run: npm run update-index
- Or manually edit aircraft/index.js
- Reload page after updating
Aircraft File Missing or Misnamed
- Check aircraft/ directory for all .js files
- Verify filenames match expected IDs
- Ensure files have .js extension
JavaScript Syntax Error in Aircraft File
- Open aircraft file in text editor
- Look for missing commas, brackets, or quotes
- Validate JSON structure
- Check browser console for syntax errors
Wrong Directory Structure
- Ensure aircraft files are in aircraft/ subdirectory
- Not in root directory
- Not in a nested subdirectory
Browser Cache
- Clear browser cache: Ctrl+Shift+Delete (or Cmd+Shift+Delete)
- Or hard reload: Ctrl+Shift+R (or Cmd+Shift+R)

Calculations Seem Incorrect

Symptom: Calculated weights or CG positions don't match manual calculations

Possible Causes and Solutions:

Incorrect BEW Values
- Verify BEW, arm, and moment are correct
- Check against aircraft weight and balance report
- Update if values have changed
Wrong Station Arms
- Open aircraft configuration file
- Verify each station arm matches flight manual
- Correct any typos or transposed digits
Fuel Moment Table Errors
- Check fuel table data against flight manual
- Verify values are Moment/100 (not full moments)
- Ensure values are in ascending order
- Check for missing or duplicate entries
Rounding Differences
- Small differences (<0.1%) are normal
- Due to rounding in intermediate calculations
- Not a concern for practical use
Envelope Data Incorrect
- Verify envelope points match flight manual
- Check that polygon is closed (first = last point)
- Ensure points are in correct order

Validation Method:

Perform manual calculation:

Weight = BEW + Occupants + Baggage + Fuel
Moment = BEW_moment + Occupant_moments + Baggage_moments + Fuel_moment
CG = (Moment / Weight) × 100

Compare with calculator results
If difference > 1 lb or 0.1 inch, investigate further
Check each component individually

PDF Generation Not Working

Symptom: "Download PDF" button doesn't work or PDF is blank/corrupt

Possible Causes and Solutions:

jsPDF Library Missing
- Verify jspdf.umd.min.js exists in root directory
- Re-download if missing or corrupted
- Check file size (should be ~200-400 KB)
Browser Pop-up Blocker
- PDF opens in new window/tab
- Browser may block pop-ups
- Allow pop-ups for this page
- Or check browser toolbar for blocked pop-up notification
Incomplete Data Entry
- Fill all required fields
- Ensure calculations have run (status cards show values)
- Try entering more data and generating again
Logo Issues
- If logo path is incorrect, PDF generation may fail
- Edit aircraft configuration
- Use base64 logo or remove logo reference
- Regenerate PDF
Browser Compatibility
- Try different browser
- Update browser to latest version
- Clear cache and retry
Canvas Not Rendering
- Envelope plot must render before PDF generation
- Wait for plot to appear
- Then click "Download PDF"

Standalone Version Issues

Symptom: Standalone file doesn't work or displays incorrectly

Possible Causes and Solutions:

Incomplete Generation
- Regenerate standalone file
- Verify file size is 1-2 MB
- Check for console errors during generation
Transfer Corruption
- File may have corrupted during email/transfer
- Re-transfer using different method
- Verify file size matches original
Mobile Browser Compatibility
- Use Safari on iOS (recommended)
- Or Chrome/Brave
- Update browser to latest version
Insufficient Memory (Mobile Devices)
- Large file may exceed device memory
- Close other apps
- Restart device and try again
Local Storage Restrictions (iOS)
- iOS may restrict local file access
- Open file from Files app (not Mail app)
- Or upload to iCloud Drive first
Images Not Displaying
- Base64 conversion may have failed
- Regenerate standalone file
- Check that original images are readable

Advanced Topics

Multi-Aircraft vs Single-Aircraft Mode

The calculator automatically detects and adapts to deployment mode:

Multi-Aircraft Mode

Multiple aircraft configurations in aircraft/ directory
Aircraft selector dropdown appears at top
User can switch between aircraft
Ideal for flight schools with varied fleet

Single-Aircraft Mode

Only one aircraft configuration exists
Aircraft selector is hidden automatically
That aircraft loads by default
Ideal for single-aircraft operators

Switching Modes:

To convert from single to multi-aircraft:

Add additional aircraft files to aircraft/ directory
Run npm run update-index
Reload page; selector appears automatically

To convert from multi to single-aircraft:

Remove all but one aircraft file from aircraft/ directory
Run npm run update-index
Reload page; selector disappears automatically

Deployment Considerations:

Multi-aircraft: Users can explore multiple aircraft
Single-aircraft: Simpler interface, faster loading
Choose based on your operational needs

Customizing the Visual Theme

The calculator uses CSS custom properties (variables) for easy theme customization.

Color Scheme Variables (in index.html <style> section):

:root {
  --ink: #000000;              /* Primary text color */
  --muted: #666666;            /* Secondary text color */
  --card: #ffffff;             /* Card background color */
  --bg: #f5f5f5;               /* Page background color */
  --border: #e0e0e0;           /* Border color */
  --accent: #0066cc;           /* Accent color (links, buttons) */
  --success: #28a745;          /* Success/green status */
  --danger: #dc3545;           /* Error/red status */
  --warning: #ffc107;          /* Warning/yellow status */
}

Customizing Colors:

Open index.html in text editor
Locate the :root section in <style> tag
Modify color values (use hex, rgb, or named colors)
Save and reload

Example - Dark Mode:

:root {
  --ink: #ffffff;
  --muted: #aaaaaa;
  --card: #2a2a2a;
  --bg: #1a1a1a;
  --border: #444444;
  --accent: #4da3ff;
  --success: #4caf50;
  --danger: #f44336;
  --warning: #ff9800;
}

Example - High Contrast:

:root {
  --ink: #000000;
  --muted: #333333;
  --card: #ffffff;
  --bg: #ffffff;
  --border: #000000;
  --accent: #0000ff;
  --success: #008000;
  --danger: #ff0000;
  --warning: #ffcc00;
}

Font Customization:

Change the font family:

body {
  font-family: 'Arial', 'Helvetica', sans-serif;
}

Options:

'Georgia', serif - Classic serif font
'Courier New', monospace - Monospace font
'Verdana', sans-serif - Clean sans-serif
'Roboto', sans-serif - Modern Google Font (requires internet)

Adding Custom Logos

For Screen Display:

Prepare Logo Image
- Format: PNG or JPG recommended
- Size: 100-200 pixels wide recommended
- Transparent background (PNG) works best
Add to Images Directory
- Copy logo file to Images/ directory
- Example: Images/my_aircraft_logo.png
Update Aircraft Configuration
- Open aircraft .js file in text editor
- Find logo: property
- Update filename:
```
logo: "my_aircraft_logo.png",
```
Test
- Reload calculator
- Select aircraft
- Verify logo displays at top of page

For PDF Reports (requires base64):

Convert Logo to Base64
- Use online converter: search "image to base64"
- Upload your logo file
- Copy complete data URI (includes data:image/png;base64, prefix)
Update Aircraft Configuration
- Open aircraft .js file
- Find logoBase64: property
- Replace with your base64 string:
```
logoBase64: "data:image/png;base64,iVBORw0KGgoAAAANS..."
```
Test PDF Generation
- Open calculator
- Generate PDF
- Verify logo appears in PDF

Logo Best Practices:

Keep file size under 100 KB for faster loading
Use transparent background for professional appearance
Ensure adequate contrast with page background
Test on different devices and screen sizes

Creating Aircraft Backups

Regular backups protect against accidental data loss.

Automatic Backups:

When using the test scenario generator:

Automatic backup created before each generation
Saved to aircraft/backups/ directory
Filename includes timestamp: cj3_backup_20241117_143052.js

Manual Backups:

Method 1: Copy Files (Simple)

cp aircraft/cj3.js aircraft/cj3_backup_2024-11-17.js

Method 2: Backup Directory (Recommended)

mkdir aircraft/backups
cp aircraft/*.js aircraft/backups/

Method 3: Version Control (Best)

git init
git add aircraft/
git commit -m "Backup aircraft configurations"

Restoring from Backup:

Locate Backup File
- Check aircraft/backups/ directory
- Or your manual backup location

Copy to Active Location

cp aircraft/backups/cj3_backup_20241117_143052.js aircraft/cj3.js

Verify Restoration
- Open calculator
- Select restored aircraft
- Verify configurations are correct

Backup Best Practices:

Backup before major changes
Keep multiple versions (at least 3 most recent)
Test backups periodically
Store off-site for critical configurations
Document what changed between versions

Contributing

Contributions to improve this weight and balance calculator are welcome.

Ways to Contribute:

Report bugs or issues
Suggest new features
Add aircraft configurations
Improve documentation
Submit code improvements
Share usage experiences

Reporting Issues:

When reporting a problem, include:

What you were trying to do
What happened (actual behavior)
What you expected to happen
Browser and version
Aircraft configuration (if relevant)
Steps to reproduce the issue

Submitting Aircraft Configurations:

If you create a configuration for an aircraft not currently included:

Test thoroughly with the aircraft's flight manual
Generate and validate test scenarios
Document any special considerations
Submit via pull request or email

Code Contributions:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit pull request with clear description

License

This project is licensed under the MIT License.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

What This Means:

Free to use for personal or commercial purposes
Free to modify and customize
Free to distribute
No warranty or guarantee provided
Use at your own risk

Aviation Safety Notice:

This software is provided as a training and planning tool. While calculations are based on manufacturer data and aviation industry standards:

Always verify results against official aircraft documentation
Use certified weight and balance methods for actual flight operations
Follow all applicable regulations and procedures
The authors assume no liability for operational use

Support

Documentation: This README provides comprehensive information about all features and functionality.

GitHub Repository: https://github.com/rjsears/multi-aircraft-web-weight_balance

Issues and Questions:

Check this README first
Review the Troubleshooting section
Search existing GitHub issues
Open a new issue if needed
Issues: GitHub Issues
Discussions: GitHub Discussions

Additional Resources:

test_calculations.html - See working examples
aircraft_builder.html - Interactive configuration tool
admin.html - Quick reference for utilities

Version: 1.0.0
Last Updated: November 2024
Author: Richard J. Sears / richardjsears@gmail.com

Acknowledgments

My Amazing and loving family! My family puts up with all my coding and automation projects and encourages me in everything. Without them, my projects would not be possible.
My brother James, who is a continual source of inspiration to me and others. Everyone should have a brother as awesome as mine!

Name		Name	Last commit message	Last commit date
Latest commit History 178 Commits
aircraft		aircraft
ios-app		ios-app
.gitignore		.gitignore
LICENSE		LICENSE
LOFT_logo_130x100.png		LOFT_logo_130x100.png
README.md		README.md
Top500.png		Top500.png
Top525.png		Top525.png
Top525b.png		Top525b.png
Top560XL.png		Top560XL.png
TopCL350.png		TopCL350.png
admin.html		admin.html
aircraft_builder.html		aircraft_builder.html
create_standalone.js		create_standalone.js
generate_tests.js		generate_tests.js
index.html		index.html
index_standalone.html		index_standalone.html
jspdf.umd.min.js		jspdf.umd.min.js
map_background.gif		map_background.gif
package.json		package.json
test_calculations.html		test_calculations.html
test_math.js		test_math.js
update_aircraft_index.js		update_aircraft_index.js

Folders and files

Latest commit

History

Repository files navigation

Multi-Aircraft Weight & Balance Calculator

Table of Contents

Overview

What This Application Does

Key Features

Supported Aircraft

No Web Server Required

Installation

Basic Installation

Directory Structure

Installation Verification

Quick Start

Opening the Application

Testing with Included Aircraft

Understanding Training vs Checking Mode

Using the Weight & Balance Calculator

Selecting an Aircraft

Entering Flight Data

Understanding the Status Display

Reading the CG Envelope Plot

Generating PDF Reports

Updating Basic Empty Weight (BEW)

Why Update BEW

How to Update BEW

Testing After BEW Updates

Building a New Aircraft Configuration

Prerequisites

Using the Aircraft Builder

Step 1: Basic Information

Step 2: Mean Aerodynamic Chord (MAC) Configuration

Step 3: Chart Axes

Step 4: CG Envelope Definition

Step 5: Weight Limits

Step 6: BEW Defaults

Step 7: Defining Stations

Step 8: Field Limits

Step 9: Fuel Moment Table

Step 10: Generate and Download

Step 11: Installing Your New Aircraft

Creating Standalone Deployments

What is a Standalone Deployment

When to Use Standalone Mode

Creating the Standalone File

Deploying to iPad or Mobile Devices

Optional: Deploying with a Web Server

Why Use a Web Server

Apache Configuration

Nginx Configuration

Simple Python Web Server

Node.js Web Server

Admin Panel

Accessing the Admin Panel

Admin Panel Features

Generating Test Scenarios

Test Calculations Tool

Purpose of Test Calculations

Using the Test Calculator

Understanding Test Results

Command-Line Utilities

Prerequisites for CLI Tools

Generating Test Scenarios (CLI)

Validating Calculations (CLI)

Updating Aircraft Index

Creating Standalone Files (CLI)

Understanding the Calculations

Weight and Balance Method

Center of Gravity (CG) Calculation

Percent Mean Aerodynamic Chord (%MAC)

Fuel Moment Interpolation

Envelope Containment

Troubleshooting

Application Won't Load

Aircraft Not Appearing

Calculations Seem Incorrect

PDF Generation Not Working

Standalone Version Issues

Packages