Skip to content

Add documentation #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bquan0 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add documentation #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 112 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,125 @@
# level-gen
This repo provides scripts to generate scene files for Godot from radiation geometries in ACIS (.sat) files.

## How to use `stl_to_tscn.py`
To use this script, run
`python3 stl_to_tscn.py <json file>`

Using this script requires a `<json file>` which contains information about the location of the input `.stl` files, location of the output `.obj` and `.tscn` files, and the texture to apply to each `.stl` file. An example can be found at [input.json](stl_to_obj/input.json).

The `.json` file should have a `header` object, which contains:
|Parameter|Description|
|---|---|
|`input_folder`| Folder that contains the `.stl` files. All `.stl` files should be in this folder and not inside a sub-folder in this folder. |
|`output_folder`| Location where the `.obj` and `.tscn` files should be generated in |
|`scale`| A number indicating the unit of distance in the `.stl` files. The units in Godot are meters. (Ex. if the `.stl` file was in cm, `scale` should be `0.01`)|
|`extra_textures`| `.json` file that contains information about additional textures not included in `textures.json`|

It should also have a `meshes` object, which is an array of objects. Each object contains information about an `.stl` file.
|Parameter|Description|
|---|---|
|`stl_file`| Name of the `.stl` file with the `.stl` extension. |
|`uv_map`| Since `.stl` files do not have information for textures, this script applies a UV map in Blender to make textures appear correctly. Choose between `smart`, `cube`, `cylinder`, `sphere`, `unwrap` based on the geometry of your `.stl` file. |
|`texture`| Name of the folder that has the `.jpgs` for the textures in the `texture` folder in the Godot game. |
|`collisions`| `true` if the player can't walk through this mesh, `false` otherwise. It is not recommended to enable collisions for very complex meshes because it will cause lag in Godot. Instead, you should manually add simpler collisions in Godot. |
|`mesh_compression`| `.stl` files only use triangles. Applying mesh compression and combining these triangles decreases the size of the output `.obj` files and lag in Godot. Choose between `limited_dissolve` and `tris_to_quads`.

### Extra textures `.json` file
You can also specify other textures that aren't in the provided textures folder in the `vr-game` repo. An example is provided in [more_textures.json](stl_to_obj/more_textures.json).

This `.json` file should contain one `textures` object with an array of objects with the following parameters:

|Parameter|Description|
|---|---|
|`folder`| Name of the folder that contains the `.jpg` or `.png` files for the textures|
|`jpg_dict`| Dictionary that contains `jpg` files used for various aspects of texture. Right now, `stl_to_tscn.py` handles the following aspects: `albedo`, `roughness`, `metallic`, `normal`, and `depth`. |
|`other_textures`| Dictionary that contains textures that DON'T use `.jpg` files. An example can be seen in [textures.json](stl_to_obj/textures.json). The parameter names in this dictionary are the names of the textures. |

Note: [textures.json](stl_to_obj/textures.json) and [more_textures.json](stl_to_obj/more_textures.json) have the same format and are loaded in the same way in `stl_to_tscn.py`.

All of the provided textures that use `.jpg` files were found at [ambientcg.com](https://ambientcg.com/). You can use this site to get more free textures!


### Walkthrough Tutorial
Start by downloading the `.stl` files from [this Google Drive folder](https://drive.google.com/drive/folders/1S3hG1KLQOmmThyw3faT12uktwIfhQtQq?usp=drive_link). This link is currently only available for those with a UW-Madison Google account. Next, either:
* create a new folder named `tworoom_stl` inside the `stl_to_obj` folder and place the `.stl` files in `tworoom_stl`
* OR change the `input_folder` field of `input.json` to match the location of the folder that contains the `.stl` files.

Next, run the script with: `python3 stl_to_tscn.py input.json`

To visualize the scene file, you will need the vr-game Godot project. Follow the instructions in the `README.md` of the [vr-game repo](https://github.com/cnerg/vr-game) for setting up the Godot project.

Put the generated folder (default name is `tworoom`) into the folder that contains the Godot project. For best practices, put the folder in the `models` folder. Now, you can open the `.tscn` file and view the Two Room model with its textures and collisions.

To play the level, create a new Scene and drag in `Player.tscn` and the `.tscn` of the generated room (default name is `tworoom.tscn`). Then, save the Scene inside the `scenes` folder and press the "Play Scene" button at the top right. This will allow you to move around your generated scene and test if collisions are working.

NOTE: the generated "level" is only the `.stl` geometries and textures. It doesn't have any radiation data, so the Geiger counter will not detect any radiation in the Scene.


## How to use cubitExportSTL.py
This module will export all groups in cubit into .stl files AND create a template file, which can be used as input for stl_to_tscn.py
This module will export all groups in Cubit into .stl files AND create a template file, which can be used as input for `stl_to_tscn.py`.

### Cubit Download
If you don't have Cubit, you can request a free trial for [Coreform Cubit](https://coreform.com/coreform-cubit/).

### To export groups for an ACIS (.sat) file that already has groups
`python3 cubitExportSTL.py [output_folder] [sat_file location] [template type]`
```
python3 cubitExportSTL.py <output_folder> <sat_file location> <template type>`
```

This allows you to do everything from the command line. (You don't have to open Cubit.)

|Parameter|Description|
|---|---|
|`output_folder`| Folder that the generated `.stl` files and template file should be placed in. |
|`sat_file location`| Path to the `.sat` file |
|`template type`| Choose between `.csv` and `.json`. This is an optional argument that defaults to `.csv` since `.csv` files can be easily edited in Excel or Google Sheets.|

### To export groups while using Cubit GUI
1. Open Cubit and import the cubitExportSTL module
`import cubitExportSTL`
1. Open Cubit. In the "Command Line", import the cubitExportSTL module. Make sure you swap to the "Python" mode before doing this!
```
import cubitExportSTL
```
If you get a `ModuleNotFoundError`, you can either run this:

```
import sys
sys.path.append(“<folder that contains cubitExportSTL.py>”)
```

or search up a way to add the folder that contains the module to your PATH env variable.
2. Create groups of Volumes. Each group will be exported to its own .stl file.
3. Run this in Cubit:
`cubitExportSTL.export_groups(cubit, "<folder to export stl files and .json file to>")`

2. Create groups of Volumes that you want to **have the same texture**. This is because each group will be exported to its own `.stl` file with the same name as the group, and each `.stl` file only gets 1 texture applied to all its meshes in `stl_to_tscn.py`.
3. Run this in the "Command Line", replacing the parameters with respective strings.
```
cubitExportSTL.export_groups(output_folder, template)
```

### Defining groups in Cubit GUI
In the "Model Tree" left panel, right-click "Groups" > "Create New Group". The name of the group will be the name of the `.stl` file that contains the volumes inside the group.

To add volumes to a group, shift-click all the volumes you want to add to the group. Then, right-click and select "Add to Group/BC". Then, click on the group you want to add the volume to and click "OK".

### Exporting ACIS file with groups
Make sure "Export Attributes" is checked, otherwise your groups will NOT be included in the ACIS file.

### Example Files
* [tworoomWithGroups.sat](https://drive.google.com/file/d/1w6arEqjzZrolht1bn8Ah_WWnn7gGnpFT/view?usp=drive_link): This comes with pre-defined groups.
* [tworoom.sat](https://drive.google.com/file/d/142d7zFMn2s6L95ajV0rZcuQLCxYScvth/view?usp=drive_link): This doesn't have any groups, so you have to define them. I recommend defining the following groups: walls, ceiling, floor, shield, radioactivecylinder.



## How to use `mcnp_to_csv.py`
This script takes a `.txt` file with MCNP data and generates a `.csv` file that has two sections:
1. Three lines which contain the boundaries of voxels for the X, Y, Z axes.
2. Lines which each contain the XYZ coordinates of the center point of a voxel, radiation result, and relative error (in that order).

Example run:
```
python3 mcnp_to_csv.py <mcnp .txt file> <output .csv file>
```

The generated `.csv` file can be used in the [vr-game repo](https://github.com/cnerg/vr-game) as an input to the `initialize()` function in child classes of `MCNPMesh.gd`. One such child class is `RadioactiveRoom.gd`.

### Example Files
* [tworoom10msht.txt](https://drive.google.com/file/d/15RGQn6SXnR7_yjMz3PxmkMOp67A_PmeR/view?usp=drive_link): MCNP data for the Two Room model.
4 changes: 2 additions & 2 deletions stl_to_obj/input.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"header": {
"input_folder": ".",
"output_folder": "TwoRoom2",
"input_folder": "tworoom_stl",
"output_folder": "tworoom",
"scale": 0.01,
"extra_textures": "more_textures.json"
},
Expand Down