EngD Project Pull Request

[Timo9Madrid7]

Maintainer Manual

• 1. Feature: Upload .obj Only
  • 1.1. How to Enable This Function?
  • 1.2. Why Is the Default Value Set to False?
  • 1.3. How to extend upload?
• 2. Feature: User Parameter Setting
  • 2.1. How to Create a Setting Template for a Method?
  • 2.2. How to Retrieve and Use the Settings?
• 3. Feature: Auralization
  • 3.1. How Does Auralization Work?
  • 3.2. How to Add More Default Audio Examples for Users?
• 4. Feature: Export Simulation Results
  • 4.1. How Does Export Work?
  • 4.2. Simulation Export API
  • 4.3. How to extend the export?
• 5. Flask Commands

This manual provides an overview of new features for maintainers—things you should know before contributing to this project.

1. Feature: Upload .obj Only

1.1. How to Enable This Function?

In config.py, there is a class FeatureToggle(DefaultConfig) with a commented-out attribute:
enable_geo_conversion = True.

To enable this feature, simply uncomment it.

1.2. Why Is the Default Value Set to False?

We found that using a .geo file converted from .obj produces slightly different results compared to using the original .geo file. However, the differences are minimal. Since we currently lack the expertise to fully analyze this impact, we have left this feature disabled by default.

1.3. How to extend upload?

Currently the system support .geo, .obj, and .dxf to be able to add more method look into factory.geometry_converter_factory. On that folder we can add other conversion method such as GltfConversion.py and then register it in the GeometryConversionFactory.py. Then to allow file upload enable the newly supported file in BE and FE. On the BE you can do it by adding the option into config.py on ALLOWED_EXTENSIONS parameter. On the FE can be done by adding it on ImportModelStep1.tsx then look for this line <Uploader disabled={importStarted} accept={'.obj,xxx'} then add it beside other file.

2. Feature: User Parameter Setting

2.1. How to Create a Setting Template for a Method?

Follow these steps:

1. Create a Template

   • Create a .json file in the example_settings folder, following the format of example_settings\de_setting.json.
   • The system currently supports four UI components for parameter settings: textbox, slider, checkbox, and radio.
   • It is recommended to set a default value for the user, however, if there are no preferred values, you can choose to remove default (recommended) or set default=null (warnings in frontend).

2. Register Your Template

   • In app\models\data\simulation_settings.json, create an object with the following properties:
     • name: The filename created in Step 1.
     • label: The name displayed on the UI.
     • description: (Optional) A brief description of this method.
     • simulationType: The corresponding simulation name stored in the database.

3. Add simulationType to the Library

   • In app\types\Task.py, add simulationType to TaskType(Enum) to ensure consistency and ease of reference.
   • For example, in simulation.taskType.value in (TaskType.DE.value, TaskType.BOTH.value):, using TaskType.DE instead of a hardcoded "DE" string provides better code hints and ensures global consistency if renaming is needed.

4. Run the Update Command

   • Execute flask update-setting to register the settings in the database.

5. (Optional) Update a Setting File

   • Direct modifying the .json file is sufficient; no further operations are required.

2.2. How to Retrieve and Use the Settings?

Settings are stored in both develop.db -> simulations -> solverSettings and corresponding MeasurementRoom_xxx..._x.json file in field simulationSettings.

3. Feature: Auralization

3.1. How Does Auralization Work?

The implementation follows the process outlined by Ilaria in Diffusion\Auralization\AuralizationFunctionFrequency.py.

• Only the essential parts of the original code were retained, while unnecessary elements (e.g., plot visualization) were removed.
• The convolution operation, originally performed using numpy, has been replaced with scipy, as scipy handles multi-channel audio more efficiently.
• The results were verified using np.allclose, ensuring consistency between the original and modified versions.

3.2. How to Add More Default Audio Examples for Users?

Follow these steps:

1. Move Your Audio File

   • Place the .wav file in the example_audios directory.

2. Register the Example

   • In app\models\data\audio_files.json, create an object with the following properties:
     • name: The name displayed on the UI.
     • filename: The filename added in Step 1.
     • description: (Optional) A brief description of this example.
     • fileExtension: The file type (currently only supports .wav).

3. Run the Update Command

   • Execute flask update-audio to register the new example in the database.

4. Feature: Export Simulation Results

4.1. How Does Export Work?

Previously, after a simulation was completed, results (excluding impulse response) were stored in a .json file.

Now, all results are also stored in a separate .xlsx file, as reading/writing from .xlsx is more efficient than loading a .json file. The impulse response is then calculated using auralization_calculation, and the results are stored in the .xlsx file.

As a result, the .xlsx file now contains three sheets:

• Parameter
• EDC
• Impulse response

This entire process runs alongside the simulation, which means the progress bar may not immediately reflect completion. Even after the simulation appears to be finished, an additional few seconds are required to generate the final .xlsx file.

4.2. Simulation Export API

New API implemented due to enable custom export for simulation results. The API utilizes POST request as a communication method between frontend and backend. Below is the structure and explanation of the request followed by custom export example:
Structure:

{
   "xlsx": ["<boolean>"], 
   "Parameters": ["<list of string>"], 
   "EDC": ["<list of string>"],
   "Auralization": ["<list of string>"],
   "SimulationId": ["<list of number>"]
}

Explanation:

• xlsx – Exports all simulation results in .xlsx format.
• Parameters – Exports selected parameters in .csv format. Available options: edt, t20, t30, c80, d50, ts, spl_t0_freq.
• EDC – Exports selected plots in .csv format. Available options: 125Hz, 250Hz, 500Hz, 1000Hz, 2000Hz.
• Auralization – Exports selected auralization data in .csv format. Available options:
  • wav – Auralized sound in .wav format.
  • wavIR – Impulse response in .wav format.
  • csvIR – Impulse response in .csv format.
• SimulationId – A unique simulation ID for export.

Custom export example:

{
"xlsx": ["true"],
"Parameters": ["edt","t20"],
"EDC": ["125Hz","250Hz"], 
"Auralization": ["wav","csvIR"], 
"SimulationId": [1]
}

The API backend is implemented in app\factory\export_factory. The folder contains strategy.py and factory.py classes which can be extendable by adding new specific export to the factory class. The purpose of the factory is to specify various export methods such as auralization, excel, parameters and plots, whereas strategy is an abstract export method.

4.3. How to extend the export?

1. Create new export class implementing the abstract methods in strategy.py
2. Register the new export type in factory.py to ensure the factory can create it

5. Flask Commands

clean-cache     Clean cache in the upload folder.
cov             Run the unit tests with coverage
cov-html        Run the unit tests with coverage and generate an HTML...
create-db       Create Database.
db              Perform database migrations.
drop-db         Drop Database.
openapi         OpenAPI commands.
reset-db        Reset Database.
routes          Show the routes for the app.
run             Run a development server.
shell           Run a shell in the app context.
tests           Run the tests without code coverage
update-audio    Update audio files based on Json file.
update-setting  Update setting files based on Json file.