update spot_utils doc

predicators/spot_utils/README.md

@@ -1,5 +1,38 @@
 # Spot Utils
 
+## How to run your own Spot environment
+
+> Last Updated: 04/11/2024
+
+**Steps:**
+- Set up the codebase, perception pipeline, and Spot
+  - You need to have access to a GPU server for the perception pipeline (e.g., the Detic-SAM pipeline)
+  - You need to connect to Spot (through WiFi or ethernet cable). Spot in its own WiFi AP mode is on IP `192.168.80.3`.
+  - To connect to both Spot and GPU server, our current solution is to use WiFi for Spot and ethernet cable for the GPU server.
+- Create a new map of the environment: See the `Mapping` section.
+  - Prepare the metadata file: See the `Prepare Metadata` section.
+- Implement your task
+- Start actual run. Examples:
+```
+# template
+python predicators/main.py --spot_ip <spot_ip> --spot_graph_nav_map <map_name> --env <env_name>
+
+# an example to run LIS Spot
+python predicators/main.py --spot_ip 192.168.80.3 --spot_graph_nav_map b45-621 --env lis_spot_block_floor_env --approach spot_wrapper[oracle] --bilevel_plan_without_sim True --seed 0
+```
+
+### Implement Your Task
+
+To create a simple task before you can run, you only need to:
+
+- Create a new environment in `envs/spot_envs.py`
+  - In `spot_env.py`, subclass the `SpotRearrangementEnv` and define the necessary methods needed to override.
+  - The simplest possible example is `SpotSodaFloorEnv` (and maybe you can directly use this!).
+  - Doing this involves selecting some operators that you'll need.
+- If you want, define a new `goal_description` string. Then, go to the _`create_goal` function of `spot_perceiver.py` and follow the example to convert a goal description string into an actual set of atoms needed to implement the goal.
+
+
+
 ## Mapping
 > Last Updated: 11/14/2023
 
@@ -15,17 +48,31 @@ To create a new map of a new environment:
    the spot around the environment. The script is [here](https://github.com/boston-dynamics/spot-sdk/blob/master/python/examples/graph_nav_command_line/recording_command_line.py)   
 3. Save the map files to spot_utils / graph_nav_maps / <your new env name>
 4. Create a file named `metadata.yaml` if one doesn't already exist within the folder
-associated with a map. Populate this with details such as a `spot-home-pose`, etc.
-See `predicators/spot_utils/graph_nav_maps/floor8-v2/metadata.yaml` for an example and
-explanation(s) of the various fields in the metadata file.
+associated with a map. See below for more details.
 5. Set --spot_graph_nav_map to your new env name.
 
-### Obtaining points for the `allowed-regions` in the metadata
+
+### Prepare Metadata
+
+The metadata file is a yaml file that contains information about the map and is used by the codebase to make decisions about the environment. 
+See `predicators/spot_utils/graph_nav_maps/floor8-v2/metadata.yaml` or `predicators/spot_utils/graph_nav_maps/floor8-sweeping/metadata.yaml` for an example and
+explanation(s) of the various fields in the metadata file.
+
+**Specifying the following required fields**
+
+- `spot-home-pose`: a place in the room from which most of the room is visible and the robot can execute its object finding procedure.
+- `allowed-regions`: these are (x,y) points that define 4 corners of a region that the robot will be allowed to be in. This is to prevent it from trying to navigate into a wall, or outside a door. In the case of 621, you should basically just put in the 4 corners of the room. _See below for a note._
+- `known-immovable-objects`. These are the x, y, z positions of objects that the robot cannot manipulate (e.g. the floor). You'll probably want to add the floor and or any big tables in the room
+- `static-object-features`. These are some hand-defined features for various objects that you might want to use (e.g., the object shape, width, length, height, etc.).
+
+
+
+**Obtaining points for the `allowed-regions` in the metadata**
+
 A challenging thing for the metadata is to define the points that yield `allowed-regions`.
 The following workflow is one way to make this relatively easy.
 
-1. Run [this script](https://github.com/boston-dynamics/spot-sdk/tree/master/python/examples/graph_nav_extract_point_cloud) on the pre-made
-map to yield an output `.ply` pointcloud file.
+1. Run [this script](https://github.com/boston-dynamics/spot-sdk/tree/master/python/examples/graph_nav_extract_point_cloud) on the pre-made map to yield an output `.ply` pointcloud file.
 2. Install the [Open3D package](http://www.open3d.org/docs/release/getting_started.html) with `pip install open3d`.
 3. Open up a python interpreter in your terminal, and run the following commands:
 ```