OPENFLIGHT - ✈Aircraft Modeler

Aircraft Geometry Viewer & GLB Loader - Software Manual

Version: 1.0 (Based on provided code analysis)

1. Introduction

Purpose:

The Aircraft Geometry Viewer & GLB Loader is a web-based tool designed for visualizing and editing basic aircraft geometry definitions. It allows users to create, modify, and view aircraft components like lifting surfaces (wings, tails) and fuselages in a 3D environment. Additionally, it supports importing, positioning, and scaling 3D models in the GLB format to be viewed alongside the generated geometry.

Target Audience:

This tool is suitable for aerospace engineers, students, researchers, and hobbyists who need to visualize aircraft layouts, check component placement, or prepare simple geometry definitions.

Key Features:

3D visualization of aircraft lifting surfaces and fuselages using Babylon.js.
Creation, editing, and deletion of lifting surfaces and fuselages via interactive modals.
Loading aircraft definitions from .json files.
Saving the current aircraft definition to a .json file.
Importing 3D models in .glb format.
Interactive manipulation (positioning, rotation, scaling) of imported GLB models using UI controls and direct manipulation gizmos.
Direct editing of the underlying JSON data structure using an integrated JSON editor.
Interactive 3D scene controls (camera orbit/pan/zoom, selection, highlighting).
Visual aids like coordinate axes, ground plane, and origin marker.
Options to toggle ground visibility and component translucency.

2. Getting Started

Opening the Application:

Simply open the create_aircraft_model.html file in a modern web browser (like Chrome, Firefox, Edge, Safari).

System Requirements:

A modern web browser with WebGL support enabled.
No installation is required beyond having the HTML file and its associated src directory containing CSS and JavaScript files.

Initial View:

Upon opening, you will see:

The main 3D view canvas where the aircraft will be displayed.
A top control bar with various buttons grouped by function.
Floating buttons in the bottom-right corner for view options.
Initially, the 3D view will show the coordinate axes, an origin box, and the ground plane.

3. User Interface Overview

The application interface consists of several key areas:

Top Control Bar (#controls): Located at the very top, containing grouped controls:
- File Operations:
  - Open JSON: Opens a file dialog to load an aircraft definition from a .json file.
  - Save JSON: Downloads the current aircraft definition as an aircraft.json file.
  - Import GLB: Opens a file dialog to import a 3D model in .glb format.
  - Toggle JSON Editor: Shows or hides the JSON editor panel on the left.
- Aircraft Components:
  - Add Surface: Opens the "Add / Edit Lifting Surface" modal to define a new wing, tail, etc.
  - Add Fuselage: Opens the "Add / Edit Fuselage" modal to define a new fuselage section.
  - Clear All: Removes all currently defined lifting surfaces and fuselages (does not remove imported GLB models).
- Selection:
  - Selected: [Name]: Displays the name of the currently selected component (or "None").
  - Edit: (Enabled when a component is selected) Opens the appropriate modal to edit the selected component's properties.
  - Delete: (Enabled when a component is selected) Deletes the selected component from the definition and the scene.
- GLB Controls: (Active when a GLB model is loaded)
  - Rotation X/Y/Z (°) Inputs + Apply (): Allows setting the rotation of the loaded GLB model around the X, Y, and Z axes (in degrees). Click Apply to see the change.
  - Scale Input + Apply (): Allows setting a uniform scale factor for the loaded GLB model. Click Apply to see the change.
- View Settings:
  - Box Size Input + Update (): Changes the size of the reference box displayed at the scene origin.
Babylon.js Canvas (#renderCanvas): The main central area displaying the 3D scene, aircraft geometry, GLB models, and visual aids. You interact with the 3D view here.
JSON Editor Panel (#jsonEditorPanel):
- Slides in from the left when Toggle JSON Editor is clicked.
- Header: Shows the title "JSON Editor" and a close button (×).
- Editor Area (#jsonEditor): Displays the live window.aircraftData structure in a tree view. You can directly edit values here. Changes typically trigger an automatic update in the 3D view.
- Footer: Contains an Apply Changes button (often redundant due to automatic updates, but can force a refresh).
Bottom Floating Buttons (#bottomButtons): Located in the bottom-right corner:
- Toggle Ground (): Shows or hides the ground plane.
- Toggle Translucency (): Makes aircraft components and GLB models semi-transparent or opaque.
- Reset View (): Resets the camera to its default position and orientation.
GLB Transform Snippet (#glbTransformSnippet): A small panel appearing in the bottom-left corner when a GLB model is loaded and selected or being manipulated. It displays a code snippet reflecting the current position, rotation, and scale of the GLB model. This is useful for copying transform values for use elsewhere.
Loading Overlay (#loadingText): A temporary message ("Loading 3D Model...") displayed center-screen while a GLB file is being processed.
Modal Dialogs: Pop-up windows used for data entry:
- Lifting Surface Modal: Appears when adding/editing surfaces. Contains fields for name, mass, root position, aerodynamic properties (AR, TR, Area, Sweep, Dihedral), geometric flags (Symmetric, Vertical), inertia properties, CoG/AC positions, etc.
- Fuselage Modal: Appears when adding/editing fuselages. Contains fields for name, diameter, length, and nose position.
- GLB Edit Modal: Appears when editing a selected GLB model via the Edit button. Provides precise input fields for Scale, Rotation (X, Y, Z), and Position (X, Y, Z). Also includes a button to Generate Code Snippet.

4. Core Functionality & Workflow

Loading/Saving Aircraft Definitions:

Load: Click Open JSON, select a valid .json file conforming to the expected structure. The current scene will be cleared (except GLB models), and the loaded aircraft will be rendered.
Save: Click Save JSON to download a file named aircraft.json containing the current state of window.aircraftData (lifting surfaces, fuselages, general properties). Note: GLB model data itself is not saved in the JSON, only its transform might be if explicitly added to the structure (current implementation doesn't automatically save GLB transforms in the main JSON).

Creating/Editing Components:

Add: Click Add Surface or Add Fuselage. Fill in the details in the respective modal and click Submit. The new component appears in the scene.
Select: Single-click on a component (lifting surface, fuselage, or GLB model) in the 3D view. It will be highlighted (pink outline), and its name will appear in the "Selection" control group.
Edit: With a component selected, click the Edit button in the "Selection" group OR double-click the component in the 3D view. The appropriate modal will open, pre-filled with the component's current data. Modify the values and click Submit to apply changes.
Delete: With a component selected, click the Delete button. The component will be removed from the data and the scene.
Clear All: Click Clear All to remove all lifting surfaces and fuselages.

Importing & Manipulating GLB Models:

Import: Click Import GLB, select a valid .glb file. A loading indicator appears, and the model is loaded into the scene, parented to a special node (window.glbRoot). It might be auto-scaled and centered initially.
Transform (Top Bar): Use the Rotation X/Y/Z and Scale inputs in the "GLB Controls" group and click the associated Apply () buttons for quick adjustments.
Transform (Modal): Select the GLB model (click on it), then click the Edit button. The "Edit GLB Model Properties" modal opens, allowing precise input of Scale, Rotation (X, Y, Z), and Position (X, Y, Z). Click Apply Changes in the modal.
Transform (Direct Manipulation): Select the GLB model, then press and hold the Ctrl key. A position gizmo (arrows) will appear. Drag the arrows to move the model directly in the scene. Release Ctrl to finish.
Transform Snippet: While the GLB is selected or being manipulated, the #glbTransformSnippet panel shows its current transform values as code. You can select and copy this text. The Generate Code Snippet button in the GLB Edit modal also generates and selects this snippet.

Interacting with the 3D View:

Orbit: Click and drag with the left mouse button.
Pan: Click and drag with the right mouse button OR hold Shift and left-click-drag.
Zoom: Use the mouse wheel.
Focus: Middle-click on a point in the scene or on an object to make the camera target that point smoothly.
Revert Focus: Double-click empty space to revert the camera target to its previous position before the last middle-click focus. Press H to revert to the last target, O to revert to the original target.
Select Component: Single-left-click on a component mesh.
Edit Selected: Double-left-click on a selected component.
Direct Move: Select component, hold Ctrl, drag gizmo arrows.

Using the JSON Editor:

Toggle: Click Toggle JSON Editor to show/hide the panel.
Edit: Expand the tree view (lifting_surfaces, fuselages, etc.) and directly modify values (numbers, strings, arrays).
Automatic Update: Most changes made in the editor should automatically trigger renderAircraft() and update the 3D view in real-time.
Selection Sync: Clicking a component (lifting surface or fuselage) in the 3D view will automatically expand and highlight the corresponding entry in the JSON editor tree.
Apply Button: Click Apply Changes in the editor footer to manually trigger an update (usually not necessary).

View Options:

Use the buttons in the bottom-right corner (#bottomButtons) to toggle ground visibility, switch between opaque and translucent rendering modes for components, and reset the camera view.
Use the Box Size control in the top bar to resize the visual aid at the origin.

5. Technical Details

Coordinate System: The Babylon.js scene uses a standard Y-up coordinate system. However, the aircraftRoot node is rotated by default so that within the aircraft's local space, +X points forward, +Y points right (starboard), and +Z points up, which is a common convention in some aerospace contexts. Be mindful of this when interpreting root_LE or nose_position coordinates.
Libraries: Babylon.js (core, loaders), JSONEditor, Font Awesome (for icons).
File Structure:
- create_aircraft_model.html: Main page structure and script includes.
- src/styles/style.css: CSS rules for layout and appearance.
- src/js/: Contains various JavaScript modules:
  - ⛺_scene_setup/: Babylon.js scene, camera, light, ground setup.
  - component-creation.js: Functions to build 3D geometry from data.
  - render_aircraft.js: Clears and redraws aircraft geometry.
  - load_glb_file.js: Handles GLB import.
  - glb-editing.js: Logic for GLB manipulation via UI/modal.
  - interaction.js: Handles canvas clicks, drags, gizmo interaction.
  - ui-logic.js: Connects HTML controls to application functions, manages modals and data flow.
  - json-editor.js: Initializes and manages the JSONEditor instance.
  - scene-utils.js: Helper functions for scene operations (highlighting, metadata, etc.).
Data Store: The primary aircraft definition is stored in the global window.aircraftData object.
Reload Prevention: The application includes JavaScript to intercept standard browser reload actions (F5, Ctrl+R, closing tab) and prompt the user if potentially unsaved changes exist (based on whether aircraftData has components or a GLB is loaded).

6. Troubleshooting/FAQ

3D View is blank or shows errors: Ensure your browser supports WebGL and it's enabled. Check the browser's developer console (usually F12) for error messages.
JSON/GLB file won't load: Verify the file format is correct (.json or .glb). Check the developer console for loading or parsing errors. Ensure the JSON structure matches what the application expects.
Changes lost after closing tab/reloading: The application attempts to prevent accidental data loss, but it doesn't auto-save. Always use the Save JSON button to save your work explicitly before closing the application.
Gizmo (manipulation arrows) doesn't appear: Make sure a component (especially a GLB model) is selected and you are holding down the Ctrl key.

Page updated

Google Sites

Report abuse