Add Simulation_Logging guide, reorg docs for dev guide
Daniel Lovell
parent
45cdf740b1
commit
ecfdb490ae
|
|
@ -45,8 +45,7 @@ jobs:
|
|||
targetPlatform: ${{ matrix.targetPlatform }}
|
||||
- name: Copy Tools Directory
|
||||
run: |
|
||||
sudo mkdir -p build/${{ matrix.targetPlatform }}/Tools
|
||||
sudo cp -r Tools/ build/${{ matrix.targetPlatform }}/Tools/
|
||||
sudo cp -r Tools/ build/${{ matrix.targetPlatform }}/
|
||||
- if: matrix.targetPlatform == 'StandaloneWindows64'
|
||||
run: cd build/${{ matrix.targetPlatform }} && sudo zip -r ../build-${{ matrix.targetPlatform }}.zip * && cd -
|
||||
- if: matrix.targetPlatform == 'StandaloneWindows64'
|
||||
|
|
|
|||
92
README.md
92
README.md
|
|
@ -5,9 +5,11 @@
|
|||
[](https://github.com/PisterLab/micromissiles-unity/actions/workflows/build.yaml)
|
||||
[](https://github.com/PisterLab/micromissiles-unity/actions/workflows/test.yaml)
|
||||
[](https://github.com/PisterLab/micromissiles-unity/releases/latest)
|
||||
[](https://pisterlab.github.io/micromissiles-unity/)
|
||||
|
||||
# Documentation
|
||||
|
||||
|
||||
Documentation is hosted on the [micromissiles-unity GitHub Pages site](https://pisterlab.github.io/micromissiles-unity/).
|
||||
|
||||
# Quick Start
|
||||
|
||||
|
|
@ -31,91 +33,3 @@ You can find the latest release [here](https://github.com/PisterLab/micromissile
|
|||
* Navigate to `Privacy & Security`.
|
||||
* Click on `Open Anyway` to bypass Apple's developer check.
|
||||
|
||||
# Development
|
||||
|
||||
This guide will help you set up and run the project in development mode. You'll learn how to install Unity Hub, open the project, and navigate the main scene.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Installation Steps](#installation-steps)
|
||||
- [1. Install Unity Hub](#1-install-unity-hub)
|
||||
- [2. Clone the Project Repository](#2-clone-the-project-repository)
|
||||
- [3. Launch the Project via Unity Hub](#3-launch-the-project-via-unity-hub)
|
||||
- [4. Open the Main Scene](#4-open-the-main-scene)
|
||||
- [Next Steps](#next-steps)
|
||||
- [Additional Resources](#additional-resources)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A computer with internet access.
|
||||
- Administrative privileges to install software.
|
||||
- [Git](https://git-scm.com/downloads) installed on your system (optional, for cloning the repository).
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### 1. Install Unity Hub
|
||||
|
||||
Unity Hub is a desktop application that manages your Unity projects and installations. It simplifies the process of installing different Unity versions and launching projects.
|
||||
|
||||
**Steps to Install Unity Hub:**
|
||||
|
||||
1. Visit the [Unity Download Page](https://unity3d.com/get-unity/download).
|
||||
2. Click on **"Download Unity Hub"**.
|
||||
3. Run the downloaded installer and follow the on-screen instructions to complete the installation.
|
||||
|
||||
### 2. Clone the Project Repository
|
||||
|
||||
Obtain the project source code by cloning the repository from GitHub.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/PisterLab/micromissiles-unity.git
|
||||
```
|
||||
Alternatively, you can download the repository as a ZIP file and extract it to a preferred location.
|
||||
|
||||
### 3. Launch the Project via Unity Hub
|
||||
|
||||
|
||||
|
||||
1. **Open Unity Hub**.
|
||||
|
||||
2. **Add the Project to Unity Hub**:
|
||||
- Navigate to the **"Projects"** tab.
|
||||
- Click on the **"ADD"** button.
|
||||
- Browse to the folder where you cloned or extracted the project.
|
||||
- Select the folder containing the `Assets` folder and click on **"Select Folder"**.
|
||||
|
||||
3. **Install the Required Unity Version**:
|
||||
- Unity Hub will detect if the project requires a Unity version that is not currently installed.
|
||||
- A notification or warning icon may appear next to the project name.
|
||||
- Click on the notification and select **"Install Unity **[version]**"**.
|
||||
- Unity Hub will download and install the required Unity version automatically.
|
||||
|
||||
4. **Open the Project**:
|
||||
- Once the required Unity version is installed, click on the project name in Unity Hub to open it.
|
||||
|
||||
### 4. Open the Main Scene
|
||||
|
||||
After the project opens in Unity:
|
||||
|
||||
1. In the **Project** window (usually located at the bottom), navigate to:
|
||||
|
||||
```
|
||||
Assets/Scenes/
|
||||
```
|
||||
|
||||
2. Find the main scene file, usually named `MainScene.unity`.
|
||||
|
||||
3. Double-click on `MainScene.unity` to open it.
|
||||
|
||||
4. The scene will load in the **Scene** view. You can now run the simulation by clicking the **Play** button at the top of the Unity Editor.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Familiarize yourself with the [**Keybinds and Controls**](docs/Keybinds_and_Controls.md) to navigate and interact with the simulation.
|
||||
- Learn how to configure the simulation settings by reading the [**Simulation Configuration Guide**](docs/Simulation_Config_Guide.md).
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Keybinds and Controls](docs/Keybinds_and_Controls.md)
|
||||
- [Simulation Configuration Guide](docs/Simulation_Config_Guide.md)
|
||||
|
|
|
|||
|
|
@ -9,7 +9,8 @@ export default defineConfig({
|
|||
// https://vitepress.dev/reference/default-theme-config
|
||||
nav: [
|
||||
{ text: 'Home', link: '/' },
|
||||
{ text: 'Documentation', link: '/Keybinds_and_Controls' }
|
||||
{ text: 'Documentation', link: '/Keybinds_and_Controls' },
|
||||
{ text: 'Development Guide', link: '/Development_Guide' }
|
||||
],
|
||||
|
||||
sidebar: [
|
||||
|
|
@ -19,7 +20,8 @@ export default defineConfig({
|
|||
{ text: 'Keybinds and Controls', link: '/Keybinds_and_Controls' },
|
||||
{ text: 'Simulation Configuration Guide', link: '/Simulation_Config_Guide' },
|
||||
{ text: 'Simulation Logging', link: '/Simulation_Logging' },
|
||||
{ text: 'Coverage Reports', link: '/coverage/editmode/Report/' }
|
||||
{ text: 'Coverage Reports', link: '/coverage/editmode/Report/' },
|
||||
{ text: 'Development Guide', link: '/Development_Guide' }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -0,0 +1,88 @@
|
|||
# Development Guide
|
||||
|
||||
This guide will help you set up and run the project in development mode. You'll learn how to install Unity Hub, open the project, and navigate the main scene.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Installation Steps](#installation-steps)
|
||||
- [1. Install Unity Hub](#1-install-unity-hub)
|
||||
- [2. Clone the Project Repository](#2-clone-the-project-repository)
|
||||
- [3. Launch the Project via Unity Hub](#3-launch-the-project-via-unity-hub)
|
||||
- [4. Open the Main Scene](#4-open-the-main-scene)
|
||||
- [Next Steps](#next-steps)
|
||||
- [Additional Resources](#additional-resources)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A computer with internet access.
|
||||
- Administrative privileges to install software.
|
||||
- [Git](https://git-scm.com/downloads) installed on your system (optional, for cloning the repository).
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### 1. Install Unity Hub
|
||||
|
||||
Unity Hub is a desktop application that manages your Unity projects and installations. It simplifies the process of installing different Unity versions and launching projects.
|
||||
|
||||
**Steps to Install Unity Hub:**
|
||||
|
||||
1. Visit the [Unity Download Page](https://unity3d.com/get-unity/download).
|
||||
2. Click on **"Download Unity Hub"**.
|
||||
3. Run the downloaded installer and follow the on-screen instructions to complete the installation.
|
||||
|
||||
### 2. Clone the Project Repository
|
||||
|
||||
Obtain the project source code by cloning the repository from GitHub.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/PisterLab/micromissiles-unity.git
|
||||
```
|
||||
Alternatively, you can download the repository as a ZIP file and extract it to a preferred location.
|
||||
|
||||
### 3. Launch the Project via Unity Hub
|
||||
|
||||
|
||||
|
||||
1. **Open Unity Hub**.
|
||||
|
||||
2. **Add the Project to Unity Hub**:
|
||||
- Navigate to the **"Projects"** tab.
|
||||
- Click on the **"ADD"** button.
|
||||
- Browse to the folder where you cloned or extracted the project.
|
||||
- Select the folder containing the `Assets` folder and click on **"Select Folder"**.
|
||||
|
||||
3. **Install the Required Unity Version**:
|
||||
- Unity Hub will detect if the project requires a Unity version that is not currently installed.
|
||||
- A notification or warning icon may appear next to the project name.
|
||||
- Click on the notification and select **"Install Unity **[version]**"**.
|
||||
- Unity Hub will download and install the required Unity version automatically.
|
||||
|
||||
4. **Open the Project**:
|
||||
- Once the required Unity version is installed, click on the project name in Unity Hub to open it.
|
||||
|
||||
### 4. Open the Main Scene
|
||||
|
||||
After the project opens in Unity:
|
||||
|
||||
1. In the **Project** window (usually located at the bottom), navigate to:
|
||||
|
||||
```
|
||||
Assets/Scenes/
|
||||
```
|
||||
|
||||
2. Find the main scene file, usually named `MainScene.unity`.
|
||||
|
||||
3. Double-click on `MainScene.unity` to open it.
|
||||
|
||||
4. The scene will load in the **Scene** view. You can now run the simulation by clicking the **Play** button at the top of the Unity Editor.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Familiarize yourself with the [**Keybinds and Controls**](docs/Keybinds_and_Controls.md) to navigate and interact with the simulation.
|
||||
- Learn how to configure the simulation settings by reading the [**Simulation Configuration Guide**](docs/Simulation_Config_Guide.md).
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Keybinds and Controls](docs/Keybinds_and_Controls.md)
|
||||
- [Simulation Configuration Guide](docs/Simulation_Config_Guide.md)
|
||||
|
|
@ -1,12 +1,259 @@
|
|||
# Simulation Logging
|
||||
|
||||
This guide provides instructions on how to access and interpret the simulation logs, how they are structured by the `SimMonitor` class, and how to utilize the provided `visualize_log.py` script to analyze simulation data. Additionally, it offers guidance on creating your own scripts for custom analysis.
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
|
||||
Simulation logs capture detailed telemetry and event data from each simulation run. These logs are essential for debugging, performance analysis, and understanding the behavior of agents within the simulation.
|
||||
|
||||
Logs are exported to the `Telemetry/Logs` folder in your operating system's [persistent data path](https://docs.unity3d.com/ScriptReference/Application-persistentDataPath.html).
|
||||
|
||||
For example, on Windows, the logs will be exported to
|
||||
`C:\Users\<user>\AppData\LocalLow\BAMLAB\micromissiles\Telemetry`.
|
||||
For example, on Windows, the logs are exported to:
|
||||
|
||||
On MacOS, the logs will be exported to
|
||||
`~/Library/Application Support/BAMLAB/micromissiles/Telemetry`.
|
||||
```
|
||||
C:\Users\<user>\AppData\LocalLow\BAMLAB\micromissiles\Telemetry\Logs
|
||||
```
|
||||
|
||||
On macOS, the logs are exported to:
|
||||
|
||||
```
|
||||
~/Library/Application Support/BAMLAB/micromissiles/Telemetry/Logs
|
||||
```
|
||||
|
||||
`visualize_log.py` is an example script provided to help visualize and interpret the simulation logs. It is included in the `Tools` directory of the release download.
|
||||
|
||||
|
||||
## Understanding Log Files and Directory Structure
|
||||
|
||||
### Log Directory Structure
|
||||
|
||||
Simulation logs are organized into timestamped directories within the `Logs` folder. Each simulation run generates a new directory named with the timestamp of the run.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
Telemetry/
|
||||
└── Logs/
|
||||
├── 20241002_101305/
|
||||
│ ├── sim_telemetry_20241002_101311.csv
|
||||
│ ├── sim_events_20241002_101311.csv
|
||||
│ │
|
||||
│ ├── sim_telemetry_20241002_101306.csv
|
||||
│ └── sim_events_20241002_101306.csv
|
||||
├── 20241002_012122/
|
||||
│ ├── sim_telemetry_20241002_012122.csv
|
||||
│ └── sim_events_20241002_012122.csv
|
||||
└── ...
|
||||
```
|
||||
|
||||
Each simulation run produces two main CSV files:
|
||||
|
||||
- **Telemetry Log (`sim_telemetry_*.csv`)**: Contains detailed state information for each agent at each time step.
|
||||
- **Event Log (`sim_events_*.csv`)**: Records significant events such as hits, misses, agent creation, and destruction.
|
||||
|
||||
### Log Files Generated by `SimMonitor`
|
||||
|
||||
The logging system is managed by the `SimMonitor` class in the simulation codebase.
|
||||
|
||||
```csharp
|
||||
public class SimMonitor : MonoBehaviour
|
||||
{
|
||||
// Responsible for logging simulation data
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Key Responsibilities of `SimMonitor`:**
|
||||
|
||||
- Collecting agent state data at each simulation step.
|
||||
- Writing telemetry data to `sim_telemetry_*.csv`.
|
||||
- Recording significant events to `sim_events_*.csv`.
|
||||
- Organizing logs into timestamped directories for each simulation run.
|
||||
|
||||
### Telemetry Log Structure
|
||||
|
||||
The telemetry log provides a snapshot of the simulation at each time step for every agent. Key columns include:
|
||||
|
||||
- **`Time`**: Simulation time at the log entry.
|
||||
- **`AgentID`**: Unique identifier for each agent.
|
||||
- **`AgentType`**: Type of the agent (e.g., interceptor, threat).
|
||||
- **`AgentX`**, **`AgentY`**, **`AgentZ`**: Position coordinates of the agent.
|
||||
- **`AgentVelocityX`**, **`AgentVelocityY`**, **`AgentVelocityZ`**: Velocity components.
|
||||
- **`AgentStatus`**: Current status of the agent (e.g., active, destroyed).
|
||||
|
||||
### Event Log Structure
|
||||
|
||||
The event log records significant occurrences within the simulation. Key columns include:
|
||||
|
||||
- **`Time`**: Time when the event occurred.
|
||||
- **`PositionX`**, **`PositionY`**, **`PositionZ`**: Position where the event occurred.
|
||||
- **`EventType`**: Type of event (e.g., `HIT`, `MISS`, `NEW_THREAT`, `NEW_INTERCEPTOR`).
|
||||
- **`Details`**: Additional details about the event.
|
||||
|
||||
|
||||
## Running the `visualize_log.py` Script
|
||||
|
||||
The `visualize_log.py` script helps visualize agent trajectories and significant events in a 3D plot.
|
||||
|
||||
### Locating the Script
|
||||
|
||||
After downloading and extracting the release package, you can find the script at:
|
||||
|
||||
```
|
||||
Tools/visualize_log.py
|
||||
```
|
||||
|
||||
Make sure you have Python 3 installed on your system, along with the required libraries to run the script.
|
||||
|
||||
### Required Python Libraries
|
||||
|
||||
The script depends on the following Python libraries:
|
||||
|
||||
- **`pandas`**
|
||||
- **`matplotlib`**
|
||||
- **`numpy`**
|
||||
|
||||
You can install them using `pip`:
|
||||
|
||||
```bash
|
||||
pip install pandas matplotlib numpy
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
#### Navigate to the Tools Directory
|
||||
|
||||
Open a terminal or command prompt and navigate to the `Tools` directory:
|
||||
|
||||
```bash
|
||||
cd path/to/Tools/
|
||||
```
|
||||
|
||||
#### Run the Script
|
||||
|
||||
To visualize the most recent simulation logs:
|
||||
|
||||
```bash
|
||||
python visualize_log.py
|
||||
```
|
||||
|
||||
**What the Script Does:**
|
||||
|
||||
- **Automatically Finds the Latest Logs**: If no arguments are provided, it locates the most recent `sim_telemetry_*.csv` and `sim_events_*.csv` files.
|
||||
- **Prints a Summary**: Outputs a summary of events, including total counts and timing of hits and misses.
|
||||
- **Generates a 3D Plot**: Displays agent trajectories and marks events such as hits and misses.
|
||||
|
||||
#### Specifying Log Files Manually
|
||||
|
||||
You can also provide specific file paths as arguments:
|
||||
|
||||
```bash
|
||||
python visualize_log.py path/to/sim_telemetry_file.csv path/to/sim_events_file.csv
|
||||
```
|
||||
|
||||
### Example Output
|
||||
|
||||
```
|
||||
Total number of events: 150
|
||||
|
||||
Event Counts:
|
||||
HIT: 120
|
||||
MISS: 30
|
||||
|
||||
First hit at 5.00 seconds, last hit at 15.00 seconds
|
||||
|
||||
[3D plot window opens showing trajectories and events]
|
||||
```
|
||||
|
||||
### Interpreting the Plot
|
||||
|
||||
The 3D plot displays:
|
||||
|
||||
- **Agent Trajectories**: Lines representing the paths of interceptors and threats.
|
||||
- **Colors** indicate agent types (e.g., blue for interceptors, red for threats).
|
||||
- **Event Markers**: Symbols marking where events occurred.
|
||||
- **Hits**: Marked with green circles.
|
||||
- **Misses**: Marked with red crosses.
|
||||
|
||||
### Adjusting the Visualization
|
||||
|
||||
- **View Angle**: You can rotate the 3D plot by clicking and dragging to view the simulation from different perspectives.
|
||||
- **Zoom**: Use the scroll wheel to zoom in and out.
|
||||
|
||||
## Writing Your Own Scripts
|
||||
|
||||
The simulation logs are in CSV format, making them accessible for custom analysis and visualization.
|
||||
|
||||
### Getting Started
|
||||
|
||||
- **Choose a Programming Language**: Python or MATLAB are recommended for ease-of-use and data analysis capabilities.
|
||||
|
||||
For example, using Python and the `pandas` library, you can load the telemetry and event data like this:
|
||||
|
||||
```python
|
||||
import pandas as pd
|
||||
|
||||
telemetry_df = pd.read_csv('path/to/sim_telemetry_*.csv')
|
||||
event_df = pd.read_csv('path/to/sim_events_*.csv')
|
||||
```
|
||||
|
||||
### Visualization
|
||||
|
||||
- **2D Plots**: Use `matplotlib` to create time-series plots:
|
||||
|
||||
```python
|
||||
import matplotlib.pyplot as plt
|
||||
|
||||
plt.plot(telemetry_df['Time'], telemetry_df['AgentY'])
|
||||
plt.xlabel('Time (s)')
|
||||
plt.ylabel('Altitude (m)')
|
||||
plt.title('Agent Altitude Over Time')
|
||||
plt.show()
|
||||
```
|
||||
|
||||
- **3D Plots**: Use `mpl_toolkits.mplot3d` for 3D trajectory plots.
|
||||
|
||||
### Sample Script: Calculating Miss Distances
|
||||
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
|
||||
# Load telemetry and event data
|
||||
telemetry_df = pd.read_csv('path/to/sim_telemetry_*.csv')
|
||||
event_df = pd.read_csv('path/to/sim_events_*.csv')
|
||||
|
||||
# Filter miss events
|
||||
miss_events = event_df[event_df['Event'] == 'MISS']
|
||||
|
||||
# Calculate miss distances
|
||||
miss_distances = []
|
||||
for idx, miss in miss_events.iterrows():
|
||||
agent_id = miss['AgentID']
|
||||
time = miss['Time']
|
||||
# Get agent position at the time of miss
|
||||
agent_state = telemetry_df[(telemetry_df['AgentID'] == agent_id) & (telemetry_df['Time'] == time)]
|
||||
if not agent_state.empty:
|
||||
x = agent_state['AgentX'].values[0]
|
||||
y = agent_state['AgentY'].values[0]
|
||||
z = agent_state['AgentZ'].values[0]
|
||||
# Calculate distance to target or predefined point
|
||||
distance = np.sqrt(x**2 + y**2 + z**2)
|
||||
miss_distances.append(distance)
|
||||
|
||||
# Output average miss distance
|
||||
average_miss_distance = np.mean(miss_distances)
|
||||
print(f'Average Miss Distance: {average_miss_distance:.2f} meters')
|
||||
```
|
||||
|
||||
### Suggestions for Analysis
|
||||
|
||||
- **Performance Metrics**: Determine interception success rates, average time to intercept, or hit accuracy.
|
||||
- **Behavioral Analysis**: Examine how changes in simulation configurations affect agent behavior.
|
||||
- **Batch Processing**: Automate analysis over multiple simulation runs to compare different scenarios.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Python Documentation**: [pandas](https://pandas.pydata.org/), [matplotlib](https://matplotlib.org/), [NumPy](https://numpy.org/)
|
||||
|
|
|
|||
|
|
@ -10,9 +10,9 @@ hero:
|
|||
- theme: brand
|
||||
text: Documentation
|
||||
link: /Keybinds_and_Controls
|
||||
#- theme: alt
|
||||
# text: Simulation Configuration Guide
|
||||
# link: /Simulation_Config_Guide
|
||||
- theme: alt
|
||||
text: Development Guide
|
||||
link: /Development_Guide
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 254 KiB |
Loading…
Reference in New Issue