Skip to content

User Guide

Jump to bottom
KFC edited this page Apr 25, 2025 · 2 revisions

User Guide

This guide explains the features and workflow of the application in more depth. Remember that StructoPyre is currently in Beta, and some features described here may be under development or subject to change. For a shorter, more concise guide, please refer to the Basics

Table of Contents

  1. Importing 3D Models
  2. Material Mapping
  3. Assigning ACI Structural Properties
  4. Navigating the 3D Space
  5. Running the Simulation
  6. Interpreting the Visualization
  7. Settings Menu
  8. Keyboard Shortcuts Summary

1. Importing 3D Models

StructoPyre allows you to load your own building models to analyze.

  • Supported Formats: Currently, the application supports the .obj (Wavefront OBJ) 3D geometry format. It will also attempt to load an associated .mtl (Material Template Library) file if it has the same name and is selected subsequently.
  • Import Process:
    1. Click the Import button on the Main Menu.
    2. A file dialog prompts you to select the .obj file.
    3. A second dialog prompts you to select the corresponding .mtl file.
  • Model Scaling: Upon import, the application attempts to intelligently scale your model based on its detected size.
    • Automatic Scaling: Tries to guess common export scales (e.g., inches-to-meters, cm-to-meters) and adjusts accordingly.
    • Manual Scaling (via Settings): You can override the automatic scaling in the Settings menu (though this feature might be WIP) or use the Unit Conversion dropdown if available before import.

2. Material Mapping

Linking the visual materials from your model to real-world physical properties is essential for the ACI calculations.

  • Purpose: The Material Mapper UI appears after model import. It lists the material names found in your .mtl file (or assigned within the .obj). You must map these imported names to one of the predefined Aggregate Types used in ACI 216.1M-14.
  • Using the UI:
    • For each material listed on the left, use the dropdown menu on the right to select the appropriate AciAggregateCategory (e.g., Siliceous, Carbonate, Lightweight, SemiLightweight).
    • Refer to the Technical Details#aci-aggregate-types page for brief descriptions of these types and common examples, especially in the Philippine context.
    • If unsure, ACI 216 recommends using the most conservative type (usually Siliceous for fire resistance calculations).
    • Click Confirm Mappings when done.
  • Importance: This step tells the simulation engine the fundamental material properties needed for subsequent fire resistance calculations.

3. Assigning ACI Structural Properties

Crucial Note: This section describes planned functionality essential for accurate simulations. The User Interface for inputting these details is a primary focus for ongoing development.

While Material Mapping assigns the type of material, ACI fire resistance calculations depend heavily on element-specific geometric and structural properties that are usually not present in standard .obj files.

  • Why Needed: You need to tell StructoPyre about:
    • Element Type: Is a specific part of the model a Slab, Beam, Wall, or Column?
    • Concrete Cover: What is the distance (in mm) from the concrete surface to the reinforcement? (Relevant for beams, slabs, columns).
    • Equivalent Thickness: What is the effective thickness (in mm) used for barrier calculations? (Relevant for walls, slabs - especially if not simple solid slabs).
    • Restraint Condition: Is the slab/beam Restrained or Unrestrained against thermal expansion?
    • Column Dimensions: What is the least dimension (in mm) of a column?
    • (Other properties like prestressing type might be added later).
  • Planned UI (Inspector Mode & Properties Panel):
    • The goal is to allow users to select elements or groups of faces within the 3D view.
    • Pressing E will toggle the Properties Panel.
    • When an element is selected (indicated by the pink arrow), this panel will display its current assigned properties and allow the user to input/change them (e.g., set Element Type to 'Slab', enter 'Actual Cover' as 25 mm).
  • Current Beta Status:
    • The Properties Panel (E key) and Inspector Mode infrastructure exist but currently lack the input fields and element selection capability.
    • The application currently uses hardcoded default values (e.g., Type: Slab, Restraint: Unrestrained, Cover: 25 mm, Thickness: 125 mm) applied broadly after material mapping.
    • This means current simulation results are based on these defaults and will only be accurate if the user's model happens to match them. Inputting project-specific data via the Properties Panel is necessary for meaningful results.

4. Navigating the 3D Space

Explore your imported model using standard first-person controls:

  • Move: W (Forward), A (Left), S (Backward), D (Right).
  • Look: Move the Mouse.
  • Cursor: Press C to toggle the mouse cursor's visibility and lock state.
    • Cursor Hidden: Mouse controls camera look direction.
    • Cursor Visible: Mouse can interact with UI elements (when implemented).
  • (Browser Issue Note: Occasional conflicts between mouse lock and WASD keys can occur depending on the browser.)

5. Running the Simulation

This involves placing a fire source and observing the effects over time.

  • Placing Fire Source:
    • Navigate to the desired location.
    • Press X to spawn the fire source.
    • (Beta Note: This currently spawns a simple grey cube placeholder. It doesn't yet simulate heat spread or intensity.)
  • Simulation Controls (Planned UI - Simulator Mode):
    • A dedicated UI panel or section will provide buttons to:
      • Start: Begin the simulation timer and the ACI checks.
      • Pause: Temporarily halt the simulation time.
      • Reset: Stop the simulation, reset all element states and timers back to initial conditions.
  • Simulation Timer (Planned UI):
    • Will display the elapsed simulation time, typically in Hours:Minutes:Seconds (H:MM:S) format.

6. Interpreting the Visualization

The core visual feedback shows how elements withstand the fire over the simulated time according to ACI 216 calculations.

  • Color Coding:
    • 🟩 Green (Default/Safe): The element meets the ACI 216 requirements for the current elapsed simulation time based on its assigned properties.
    • 🟨 Yellow (Exposed/Warning): The element is currently exposed to the fire source (in future implementations) and/or its TimeBurning is approaching its calculated FireResistanceHours.
    • 🟥 Red (Unsafe/Failed): The element's TimeBurning has exceeded its calculated FireResistanceHours. It has failed the ACI check for that duration and is considered to have lost its required fire resistance (barrier or structural).
    • ⬛ Black (Yielded/Failed Final State): Represents an element that has definitively failed. (May be visually similar to Red in the current beta).
  • Mechanism: The SimulationManager periodically checks each element's assigned ACI properties against the requirements for the current SimulationTime (using the FireResistanceCalculator). If Actual Property < Required Property for Time T, the state changes.

7. Settings Menu

  • Access the Settings menu by clicking the Hamburger Icon (☰) located in the top-right corner of the header bar.
  • (Beta Note: Functionality within the Settings menu, such as changing scaling options or simulation parameters, is currently limited or under development.)

8. Keyboard Shortcuts Summary

  • WASD: Move Camera
  • Mouse: Look Around
  • C: Toggle Mouse Cursor Lock/Visibility
  • X: Spawn Fire Source Placeholder
  • E: Toggle Properties Panel (Inspector Mode related)

For technical implementation details, see the Technical Details page. For known issues and limitations, refer back to the Home page or a dedicated Limitations section.

Clone this wiki locally