From fcae02802f4cc845c461ed28e76e2b850789c623 Mon Sep 17 00:00:00 2001 From: bquan0 Date: Mon, 30 Dec 2024 21:32:11 -0600 Subject: [PATCH] add README.md --- README.md | 119 +++++++++++++++++++++++++++++++++++++++--- stl_to_obj/input.json | 4 +- 2 files changed, 114 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7a4984c..be8fb01 100644 --- a/README.md +++ b/README.md @@ -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 ` + +Using this script requires a `` 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