Fisheye camera docs for UE4 (#9373)

* added fisheye camera

* updated script parameters

Author: MattRoweEAIF

Docs/catalogue_scripts.md

@@ -95,20 +95,21 @@ This script launches manual control with Chrono physics, using the Sedan powertr
 
 * Script filename: `manual_control_fisheye.py`
 
-This script launches manual control with the fisheye camera model. It has some additional command line arguments for fisheye camera model parameters:
+This script launches manual control with the fisheye camera model. This script has the same key commands and command line arguments as [Manual control](#manual-control). It has some additional command line arguments for camera model parameters:
 
 | Argument | Short form | Default | Description |
 |----------|------------|---------|-------------|
 | --fov |  | 90.0 | Camera field of view angle |
 | --fov_mask |  | Not active | Mask pixels outside of FOV |
-| --fov_fade_size |  | 0.0 | Fade of FOV edge in pixels |
-| --model |  | perspective | Fisheye model:  |
-| --k0 |  | 0.0 | k0 Kannala-Brandt parameter |
-| --k1 |  | 0.0 | k1 Kannala-Brandt parameter |
-| --k2 |  | 0.0 | k2 Kannala-Brandt parameter |
-| --k3 |  | 0.0 | k3 Kannala-Brandt parameter |
-| --equirectangular |  | Not active | Image rectification |
-| --perspective |  | Not active | Image rectification |
+| --fov_fade_size |  | 0.0 | Fade of FOV edge, with the given broadening factor |
+| --model |  | perspective | Camera model: <br>perspective <br>equidistant <br>equisolid <br>orthographic <br>stereographic <br>kannala-brandt  |
+| --k0 |  | 0.0831 | k0 Kannala-Brandt parameter |
+| --k1 |  | 0.0111 | k1 Kannala-Brandt parameter |
+| --k2 |  | 0.00858 | k2 Kannala-Brandt parameter |
+| --k3 |  | 0.000854 | k3 Kannala-Brandt parameter |
+| --equirectangular |  | Not active | Equirectangular projection |
+| --perspective |  | Not active | Perspective projection |
+| --longitude_shift | 0.0 | Shifts view center by degrees for equirectangular model |
 
 #### Steering wheel
 

Docs/core_sensors.md

@@ -45,18 +45,23 @@ blueprint.set_attribute('sensor_tick', '1.0')
 
 ### Spawning
 
-`attachment_to` and `attachment_type`, are crucial. Sensors should be attached to a parent actor, usually a vehicle, to follow it around and gather the information. The attachment type will determine how its position is updated regarding said vehicle. 
-
-* __Rigid attachment.__ Movement is strict regarding its parent location. This is the proper attachment to retrieve data from the simulation.  
-* __SpringArm attachment.__ Movement is eased with little accelerations and decelerations. This attachment is only recommended to record videos from the simulation. The movement is smooth and "hops" are avoided when updating the cameras' positions.  
-* __SpringArmGhost attachment.__ Like the previous one but without doing the collision test, so the camera or sensor could cross walls or other geometries.  
+Sensors can be placed anywhere in the map. Normally they are attached to a parent actor, such as a a vehicle, to move around the simulation like a sensor physically mounted to a vehicle. The `spawn_actor()` method requires a sensor blueprint chosen from the blueprint library and a transform. In the case of an unattached sensor, the transform will define it's absolute position in the CARLA world. The `attach_to` parameter defines the actor to attach the camera to. For a sensor attached to an actor, the transform defines its relative position to the actor in the actor's coordinate system.
 
 ```py
+my_vehicle = world.spawn_actor(vehicle_blueprint, spawn_point)
 transform = carla.Transform(carla.Location(x=0.8, z=1.7))
-sensor = world.spawn_actor(blueprint, transform, attach_to=my_vehicle)
+sensor = world.spawn_actor(sensor_blueprint, transform, attach_to=my_vehicle)
+```
+
+The `attachment_type` parameter defines how the sensor's movement will be governed by the movement of its parent actor.
+
+* __Rigid attachment__ (`carla.AttachmentType.Rigid`): Movement strictly follows the parent actors's pose. This is the most common choice for normal vehicle sensors like cameras and LIDARs. It is the default attachment type setting.  
+* __SpringArm attachment__ (`carla.AttachmentType.SpringArm`): Movement is eased with little accelerations and decelerations. This attachment is recommended to record videos from the simulation. The movement is smooth and "hops" are avoided when updating the cameras' positions.  
+* __SpringArmGhost attachment__ (`carla.AttachmentType.SpringArmGhost`): Like SpringArm but without collision testing, so the camera or sensor could cross walls or other geometries.  
+
+```py
+sensor = world.spawn_actor(sensor_blueprint, transform, attach_to=my_vehicle, attachment_type=carla.AttachmentType.SpringArm)
 ```
-!!! Important
-    When spawning with attachment, location must be relative to the parent actor.  
 
 ### Listening
 
@@ -112,8 +117,9 @@ Take a shot of the world from their point of view. For cameras that return [carl
 
 |Sensor |Output | Overview       |
 | ----------------- | ---------- | ------------------ |
-| [Depth](ref_sensors.md#depth-camera) | [carla.Image](<../python_api#carlaimage>)  |Renders the depth of the elements in the field of view in a gray-scale map.          |
 | [RGB](ref_sensors.md#rgb-camera)      | [carla.Image](<../python_api#carlaimage>)   | Provides clear vision of the surroundings. Looks like a normal photo of the scene.   |
+| [Wide angle](ref_sensors.md#wide-angle-cameras)      | [carla.Image](<../python_api#carlaimage>)   | Models alternative camera models including wide-angle, fisheye and 360 degree cameras.  |
+| [Depth](ref_sensors.md#depth-camera) | [carla.Image](<../python_api#carlaimage>)  | Renders the depth of the elements in the field of view in a gray-scale map.          |
 | [Optical Flow](ref_sensors.md#optical-flow-camera)    | [carla.Image](<../python_api#carlaimage>)  | Renders the motion of every pixel from the camera.  |
 | [Semantic segmentation](ref_sensors.md#semantic-segmentation-camera)    | [carla.Image](<../python_api#carlaimage>)  | Renders elements in the field of view with a specific color according to their tags. |
 | [Instance segmentation](ref_sensors.md#instance-segmentation-camera)    | [carla.Image](<../python_api#carlaimage>)  | Renders elements in the field of view with a specific color according to their tags and a unique object ID. |

Docs/ref_sensors.md

@@ -9,6 +9,7 @@
 - [__Obstacle detector__](#obstacle-detector)
 - [__Radar sensor__](#radar-sensor)
 - [__RGB camera__](#rgb-camera)
+- [__Wide-angle camera__](#wide-angle-cameras)
 - [__RSS sensor__](#rss-sensor)
 - [__Semantic LIDAR sensor__](#semantic-lidar-sensor)
 - [__Semantic segmentation camera__](#semantic-segmentation-camera)
@@ -559,9 +560,51 @@ Since these effects are provided by UE, please make sure to check their document
 | `fov` | float | Horizontal field of view in degrees.         |
 | `raw_data`         | bytes | Array of BGRA 32-bit pixels.     |
 
+---
+
+## Wide-angle cameras
+
+* __Blueprint RGB:__ sensor.camera.rgb.wide_angle_lens
+* __Blueprint depth:__ sensor.camera.depth.wide_angle_lens
+* __Blueprint semantic segmentation:__ sensor.camera.semantic_segmentation.wide_angle_lens
+* __Blueprint instance segmentation:__ sensor.camera.instance_segmentation.wide_angle_lens
+* __Output:__ [carla.Image](python_api.md#carla.Image) per step (unless `sensor_tick` says otherwise)..
 
+The wide-angle camera models multiple types of specialized cameras such as standard wide-angle, 360 degree cameras and fisheye lenses. The wide-angle camera model offers standard RGB output along with depth, semantic segmentation and instance segmentation. There are numerous projection models available, including perspective, stereographic, equidistant, equisolid, orthographic and Kannala-Brandt.
+
+The [Kannala-Brandt](https://www.researchgate.net/publication/6899685_A_Generic_Camera_Model_and_Calibration_Method_for_Conventional_Wide-Angle_and_Fish-Eye_Lenses) model used matches the [implementation used in OpenCV](https://docs.opencv.org/3.4/db/d58/group__calib3d__fisheye.html).
+
+| Blueprint attribute  | Type     | Default  | Description          |
+| ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
+| `camera_model`       | str     | `perspective`   | Options: <br>`perspective`,<br>`stereographic`,<br>`equidistant`,<br>`equisolid`,<br>`orthographic`,<br>`kannala-brandt`|
+| `fov`    | float    | 90\.0    | Horizontal field of view in degrees.   |
+| `image_size_x`       | int      | 800      | Image width in pixels.           |
+| `image_size_y`       | int      | 600      | Image height in pixels.          |
+| `k0`       | float      | 0.0831      | Kannala-Brandt K0 parameter.          |
+| `k1`       | float      | 0.0111      | Kannala-Brandt K1 parameter.          |
+| `k2`       | float      | 0.00858      | Kannala-Brandt K2 parameter.          |
+| `k3`       | float      | 0.000854      | Kannala-Brandt K3 parameter.          |
+| `sensor_tick`        | float    | 0\.0     | Simulation seconds between sensor captures (ticks).  |
+| `fov_mask`       | bool     | false      | Masks out pixels outside of the FOV.         |
+| `fov_fade_size`       | float     | 0.0      | Amount of blur of the edge of the `fov_mask`.        |
+| `perspective`       | bool     | false      | Turns on perspective mode.         |
+| `equirectangular`       | bool     | false      | Turns on equirectangular projection.         |
+| `longitude_offset` | float | 0.0 | Shifts view center by degrees for equirectangular model |
+
+#### Output attributes
+
+| Sensor data attribute            | Type  | Description        |
+| ----------------------- | ----------------------- | ----------------------- |
+| `frame`            | int   | Frame number when the measurement took place.      |
+| `timestamp`        | double | Simulation time of the measurement in seconds since the beginning of the episode.        |
+| `transform`        | [carla.Transform](<../python_api#carlatransform>)  | Location and rotation in world coordinates of the sensor at the time of the measurement. |
+| `width`            | int   | Image width in pixels.           |
+| `height`           | int   | Image height in pixels.          |
+| `fov` | float | Horizontal field of view in degrees.         |
+| `raw_data`         | bytes | Array of BGRA 32-bit pixels.     |
 
 ---
+
 ## RSS sensor
 
 *   __Blueprint:__ sensor.other.rss