Metadata-Version: 2.4
Name: mdp_greenhouse
Version: 1.0.7
Summary: Greenhouse environment simulation for the MDP RO47007 course at TU Delft.
Author-email: R2S <C.Pek@tudelft.nl>
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: NOTICE.txt
Requires-Dist: PyYAML>=6.0
Requires-Dist: fonttools>=4.0
Requires-Dist: numpy>=1.26
Requires-Dist: matplotlib>=3.8
Dynamic: license-file
Dynamic: requires-python

# mdp-greenhouse-sim

This project represents the greenhouse simulation used during the course RO47007 ''Multidisciplinary Project'' in the Master's program robotics at TU Delft in 2026. This software simulates (simplified) greenhouse climates and allows one to query sensor values for different types of physical measurements, e.g., temperature or humidity. This project is part of the Open Educational Resources (OER) developed for the MIRTE Master robot in higher education, see [mirte.org](https://mirte.org). This software has been created by the Robust Robot Systems (R2S) section of the [Department of Cognitive Robotics](https://cor.tudelft.nl) at [TU Delft](https://www.tudelft.nl).

## Install

The MDP greenhouse simulation is available via PyPI and can be installed via:

```bash
python -m pip install mdp-greenhouse
```

## Command Line Interface of the simulator

This package installs a CLI to create, edit, read, and view created greenhouse environments. You can see an overview of commands using the `-h` flag:

```bash
mdp-greenhouse -h
```
We briefly go through the basic commands of the CLI.

### Create a new greenhouse setup

Create a new greenhouse setup in a folder with default config templates:

```bash
mdp-greenhouse --init /path/to/new-setup-folder
```
This command will create two files. The file `greenhouse_config.yaml` contains the basic information of the greenhouse, e.g., table sizes, visualization settings, and the greenhouse climate configuration. The file `tag_locations.json` contains the location of placed tables and sensor markers, including information on the available sensor measurements at each marker location.

If files already exist and you want to replace them:

```bash
mdp-greenhouse --init /path/to/new-setup-folder --overwrite
```

### Edit a greenhouse environment

Since the newly created greenhouse is empty, i.e., does not contain tables or sensor locations, we have to edit this greenhouse layout first:

```bash
mdp-greenhouse --edit /path/to/new-setup-folder
```

This command opens the edit GUI and lets you place tables in the predefined size horizontally or vertically, and place marker locations and specify which sensor values are available at a given location.
note: make sure to use unique names and IDs for use later when querying data.
note: not using a path will open the folder selection dialog box. 

### Read sensor data for a given tag ID

The read CLI allows you to read sensor data for a specific tag ID in the greenhouse. You can list available tag IDs:

```bash
mdp-greenhouse --read --list-tags --config-folder /path/to/config-folder
```

To stream sensor data for tag `tag_id` every second:

```bash
mdp-greenhouse --read <tag_id> --config-folder /path/to/config-folder
```

or from the default greenhouse:

```bash
mdp-greenhouse --read <tag_id> 
```

### View the whole greenhouse climate 

The view the whole simulated greenhouse climate, we can use the view GUI. This will show the greenhouse climate over time of the day. 

```bash
mdp-greenhouse --view /path/to/new-setup-folder
```

In the view GUI, you can select the physical measurement to view, e.g., temperature, and let the simulation playback throughout the 24 hours of a day. To speed up the simulation, you can also change the speed up factor, e.g., to simulate one minute in every real second.


## API to integrate the simulator into your code

You can also integrate the greenhouse simulation into your own code using the Python API:
```python
from greenhouse_sim.simulator import GreenhouseSimulator

sim = GreenhouseSimulator(tag_file=None, sim_config_file=None)
print(f'Available tags are {sim.tags()}')
print(f'Available sensors are {sim.sensors()}')

print(f'Retrieveing sensor data for tag {sim.tags()[0]}:')
print(sim.get_sensor_data(sim.tags()[0]))
```
This code snippet loads the greenhouse simulator either from the default config (`tag_file=None, sim_config_file=None`) or from a specified configuration. Afterwards, we print the available tags and sensor types, and receive the values for the first tag in the list.


## Configuration options

The greenhouse simulator allows different configuration options for your development in the `greenhouse_config.yaml` file:

* `speedup_factor: 1800` denotes the speed up of realtime simulation. For instance, 1800 means that one real second corresponds to 0.5 hours of simulation time.
* `debug_mode: false` if set to `true`, this flag lets the simulator use a fixed time and seed to allow reproducibility. 
* `debug_time_of_day: 12.0` time of day in hours (0-24) when debug_mode is true
* `debug_seed: 42` fixed seed for reproducibility in debug mode

To configure your own climate, you can change the sensor setup in the `greenhouse_config.yaml` file. Every physical measurement, e.g., `temperature`, is represented through basic dynamics function that adjusts the value based on the time of day using sinusoidal dynamics. Let us go through a single sensor first using the example of temperature: 

```yaml
sensors:
  temperature:
    - "value_at_midnight": 18 # This is the specified temperature value at midnight (i.e. 24:00)
      "value_at_noon": 26 # # This is the specified temperature value at noon (i.e. 12:00)
      "noise_sigma": 0 # Specify the Gaussian noise added to the sensor value
      "decay_distance": 10.67 # This specifies how the measurements decay over the position domain
      "decay_type": "linear" # The type of decay. We support linear and square decays
      "position": [5., 5.83] # The center used in the decay computation.
      "angle": 10 # Specifies the angle for the dynamics type linear
      "dynamics": "radial" # Specifies the used dynamics: Uniform values over the position space, linear gradient, or radial gradient dynamics over the position space.
```

You can also specify multiple dynamics per sensor. These dynamics are then combined in a composite sensor that returns the max of the individual sensors.


## Layout editor behavior

- tag placement snaps to `snap_step_m`
- new tables snap to `snap_step_m`
- existing tags and tables can be dragged to reposition them
- tags and tables both show hover tooltips

## Misc

Both GUIs show a startup dialog to choose:
- default config folder, or
- a custom folder containing `greenhouse_config.yaml` and `tag_locations.json`.

