Update docs for new task and sight_fov

Author: gaodechen

.gitignore

@@ -6,13 +6,12 @@ __pycache__/
 MUJOCO_LOG.TXT
 ;
 wandb/
-logdir/
 *.ipynb
 *h5
 traffic_scenarios/
 *.log
 .nfs*
-logdir/
+*logdir/
 .vscode/
 .idea/
 

README.md

@@ -157,14 +157,19 @@ The model backbones are decoupled from CarDreamer tasks or the development sutie
 Find `README.md` in the corresponding directory of the algorithm you want to use and follow the instructions to install dependencies for that model and start training. We suggest starting with DreamerV3 as it is showing better performance across our experiments. To train DreamerV3 agents, use
 
 ```bash
+# Example 1: Use default settings to train an agent
 bash train_dm3.sh 2000 0 --task carla_four_lane --dreamerv3.logdir ./logdir/carla_four_lane
+# Example 2: Override task and model parameters
+bash train_dm3.sh 2000 0 --task carla_right_turn_simple \
+    --dreamerv3.logdir ./logdir/carla_right_turn_simple \
+    --dreamerv3.run.steps=5e6
 ```
 
 The command will launch CARLA at 2000 port, load task a built-in task named `carla_four_lane`, and start the visualization tool at port 9000 (2000+7000) which can be accessed through `http://localhost:9000/`. You can append flags to the command to overwrite yaml configurations.
 
 ### Creating Tasks
 
-The section explains how to create CarDreamer tasks in a standalone mode without loading our integrated models. This can be helpful if you want to train and evaluate your own models other than our integrated DreamerV2 and DreamerV3 on CarDreamer tasks.
+The section explains how to create CarDreamer tasks in a standalone mode without loading our integrated models. This can be helpful **if you want to train and evaluate your own models** other than our integrated DreamerV2 and DreamerV3 on CarDreamer tasks.
 
 CarDreamer offers a range of built-in task classes, which you can explore in the [CarDreamer Docs: Tasks and Configurations](https://car-dreamer.readthedocs.io/en/latest/tasks.html#tasks-and-environments).
 

car_dreamer/configs/common.yaml

@@ -78,6 +78,8 @@ env:
       shape: [128, 128, 3]
       obs_range: 32
       ego_offset: 12
+      # sight_fov = 150 equivalent to [150, 150] for [front, rear] FOV
+      # Use [150, 90] to mimic human driver views
       sight_fov: 150
       sight_range: 32
       observability: full

docs/source/tasks.rst

@@ -75,7 +75,7 @@ Here is the descriptions of some common configurations in ``car_dreamer/configs/
         * ``shape`` (default: ``[128, 128, 3]``): the shape of the birdeye, should follow the form of ``[n, n, 3]``.
         * ``obs_range`` (default: ``32``): the range of the birdeye in meter (in unit of CARLA).
         * ``ego_offset`` (default: ``12``): the offset of the ego vehicle to the bottom of the birdeye in meter (in unit of CARLA).
-        * ``sight_fov`` (default: ``150``): the field of view of the camera.
+        * ``sight_fov`` (default: ``150``): the field of view of the camera. Use single value for the same front and rear FOV. Use 2-tuple to configure two angles, respectively. For example, ``[150, 90]`` can be common settings for human drivers.
         * ``sight_range`` (default: ``32``): the maximum visible distance
         * ``observability`` (default: ``full``): can be ``full, recursive_fov, fov``. ``full`` means all background vehicles are visible. ``fov`` means only vehicles in the field of view are visible. ``recursive_fov`` means vehicles in the fov of vehicles in ego's fov are also visible.
         * ``color_by_obs``: whether to color the vehicles by observability.
@@ -117,6 +117,9 @@ Here is a list of available environments and their supported tasks and configura
 .. autoclass:: car_dreamer.CarlaWptEnv
    :show-inheritance:
 
+.. autoclass:: car_dreamer.CarlaWptFixedEnv
+   :show-inheritance:
+
 .. autoclass:: car_dreamer.CarlaFourLaneEnv
    :show-inheritance:
 
@@ -126,9 +129,6 @@ Here is a list of available environments and their supported tasks and configura
 .. autoclass:: car_dreamer.CarlaOvertakeEnv
    :show-inheritance:
 
-.. autoclass:: car_dreamer.CarlaWptFixedEnv
-   :show-inheritance:
-
 .. autoclass:: car_dreamer.CarlaLaneMergeEnv
    :show-inheritance:
 
@@ -147,5 +147,8 @@ Here is a list of available environments and their supported tasks and configura
 .. autoclass:: car_dreamer.CarlaTrafficLightsEnv
    :show-inheritance:
 
+.. autoclass:: car_dreamer.CarlaFollowEnv
+   :show-inheritance:
+
 .. note::
    All configurations mentioned here can also be changed by command line arguments. For example, to change the port number of the CARLA server, you can pass ``--env.world.carla_port <number>``. See :py:func:`car_dreamer.create_task` for more details.

dreamerv3/README.md

@@ -25,7 +25,12 @@ Execute the training script with desired configurations:
 
 ```bash
 cd ..
+# Example 1: Use default settings to train an agent
 bash train_dm3.sh 2000 0 --task carla_four_lane --dreamerv3.logdir ./logdir/carla_four_lane
+# Example 2: Override task and model parameters
+bash train_dm3.sh 2000 0 --task carla_right_turn_simple \
+    --dreamerv3.logdir ./logdir/carla_right_turn_simple \
+    --dreamerv3.run.steps=5e6
 ```
 
 `2000` is the port number of the CARLA server. The script will automatically start the server so you don't need to start it manually.

dreamerv3/dreamerv3.yaml

@@ -4,6 +4,7 @@ defaults:
   task: dummy_disc
   logdir: /dev/null
   replay: uniform
+  # Use smalelr replay t osave memory; 1e5 can be suffcient for most tasks
   replay_size: 1e6
   replay_online: False
   eval_dir: ""