# sim3d.sensors.Camera

## Description

Use the `sim3d.sensors.Camera`

object to create a camera with a lens in
the 3D environment. The sensor is based on the ideal pinhole camera model, with a lens added
to represent a full camera model, including lens distortion. This camera object supports a
field of view of up to 150 degrees. For more details, see Algorithms. After you create a
`sim3d.sensors.Camera`

object, you can modify aspects of the actor object by setting
property values.

## Creation

### Description

creates a
default `camera`

= sim3d.sensors.Camera()`sim3d.sensors.Camera`

object in the 3D environment.

specifies options using one or more name-value arguments. For example, to create a camera
actor with horizontal field of view of 60, set `camera`

= sim3d.sensors.Camera(`Name=Value`

)`HorizontalFieldOfView`

to
`60`

.

### Input Arguments

**Name-Value Arguments**

Specify optional pairs of arguments as
`Name1=Value1,...,NameN=ValueN`

, where `Name`

is
the argument name and `Value`

is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.

**Example: **```
camera =
sim3d.sensors.Camera(ActorName=Camera,ImageSize=[768,1024],FocalLength=[1109,1109])
```

These intrinsic camera properties are equivalent to the properties of a `cameraIntrinsics`

(Computer Vision Toolbox) object. To obtain the intrinsic properties for your camera,
use the Camera Calibrator app.

For details about the camera calibration process, see Using the Single Camera Calibrator App (Computer Vision Toolbox) and What Is Camera Calibration? (Computer Vision Toolbox).

`ActorName`

— Name of actor

autogenerated name (default) | character array | string

Name of actor, specified as a character array or string. If you do not specify an actor name,
then the software assigns the actor an autogenerated name. Use
this argument to set the name of the
`sim3d.sensors.Camera`

object.

**Note**

If you specify the same name as an actor that already exists, then the software appends actor name you specify with a unique identifier.

`Translation`

— Relative translation

`[0,0,0]`

(default) | real 1-by-3 vector

Relative translation
(*x*,*y*,*z*) of the actor object to its
parent actor, specified as a real 1-by-3 vector, in m. Use `Translation`

to
change the position of the `sim3d.sensors.Camera`

object in the 3D environment along the
*X*, *Y*, and *Z* axes of the
coordinate system. When you add an actor to the 3D environment, the default parent actor is the
`Scene Origin`

at `(0,0,0)`

.

**Example: **`Translation=[1 2 1]`

`Rotation`

— Relative rotation

`[0,0,0]`

(default) | real 1-by-3 vector

Relative rotation (*roll*,
*pitch*, *yaw*) of the actor object to its parent actor,
specified as a real 1-by-3 vector, in rad. Use `Rotation`

to rotate the
`sim3d.sensors.Camera`

object in the 3D environment.

**Example: **`Rotation=[pi/4 pi/8 pi/2]`

`FocalLength`

— Focal length of camera

`[1109,1109]`

(default) | real-valued 1-by-2 vector of positive integers

Focal length of camera, specified as a real-valued 1-by-2
vector of positive integers of the form [*fx*, *fy*], in pixels.

*fx* = *F* ×
*sx*

*fy* = *F* ×
*sy*

where:

*F*is the focal length in world units, typically millimeters.[

*sx*,*sy*] are the number of pixels per world unit in the*x*and*y*direction, respectively.

`FocalLength`

is equivalent to the `FocalLength`

(Computer Vision Toolbox) property
of a `cameraIntrinsics`

object.

`OpticalCenter`

— Optical center of camera

`[640,360]`

(default) | real-valued 1-by-2 vector of positive integers

Optical center of camera, specified as a real-valued 1-by-2
vector of positive integers of the form [*cx*,*cy*], in
pixels. `OpticalCenter`

is equivalent to the `PrincipalPoint`

(Computer Vision Toolbox)
property of a `cameraIntrinsics`

object.

`ImageSize`

— Image size produced by camera

`[768,1024]`

(default) | real-valued 1-by-2 vector of positive integers

Image size produced by the `sim3d.sensors.Camera`

object, specified as a real-valued 1-by-2 vector of positive integers of the form
[*m*,*n*], in pixels. `ImageSize`

is
equivalent to the `ImageSize`

(Computer Vision Toolbox) property of a
`cameraIntrinsics`

object.

`RadialDistortionCoefficients`

— Radial distortion coefficients

`[0,0]`

(default) | real-valued 2-element vector | real-valued 3-element vector | real-valued 6-element vector

Radial distortion coefficients, specified as a real-valued 2-element, 3-element, or 6-element vector. Radial distortion is the displacement of image points along radial lines extending from the principal point.

As the image points move away from the principal point (positive radial displacement), image magnification decreases, and a pincushion-shaped distortion occurs on the image.

As the image points move toward the principal point (negative radial displacement), image magnification increases, and a barrel-shaped distortion occurs on the image.

The camera sensor calculates the
(*x*_{d},*y*_{d})
radial-distorted location of a point using a two-coefficient, three-coefficient, or
six-coefficient formula. This table shows the formulas, where:

(

*x*,*y*) = undistorted pixel locations*k*_{1},*k*_{2},*k*_{3},*k*_{4},*k*_{5},*k*_{6}= radial distortion coefficients of the lens*r*^{2}=*x*^{2}+*y*^{2}

Coefficients | Formula | Description |

`[k1, k2]` |
| This model is equivalent to the two-coefficient model used by the
`RadialDistortion` (Computer Vision Toolbox) property of a
`cameraIntrinsics` object. |

`[k1, k2, k3]` |
| This model is equivalent to the three-coefficient model used by the
`RadialDistortion` (Computer Vision Toolbox) property of a
`cameraIntrinsics` object. |

`[k1, k2, k3, k4, k5, k6]` | $$\begin{array}{l}{x}_{\text{d}}=x\times \frac{1+{k}_{1}{r}^{2}+\text{}{k}_{2}{r}^{4}+{k}_{3}{r}^{6}}{1+{k}_{4}{r}^{2}+{k}_{5}{r}^{4}+{k}_{6}{r}^{6}}\\ {y}_{\text{d}}=y\times \frac{1+{k}_{1}{r}^{2}+\text{}{k}_{2}{r}^{4}+{k}_{3}{r}^{6}}{1+{k}_{4}{r}^{2}+{k}_{5}{r}^{4}+{k}_{6}{r}^{6}}\end{array}$$ | The six-coefficient model is based on the OpenCV radial distortion model.
The Camera Calibrator app does not support this model. To calibrate a camera using this model, see Camera Calibration and 3D Reconstruction in the OpenCV documentation. |

`TangentialDistortionCoefficients`

— Tangential distortion coefficients

`[0,0]`

(default) | real-valued 2-element vector

Tangential distortion coefficients, specified as a real-valued 2-element vector. Tangential distortion occurs when the lens and the image plane are not parallel.

The camera sensor calculates the tangential distorted location of a point, (*x*_{d}, *y*_{d}), using this formula:

*x*_{d} = *x* + [2*p*_{1}*xy* + *p*_{2} × (*r*^{2} + 2*x*^{2})]

*y*_{d} = *y* + [*p*_{1} × (*r*^{2} + 2*y*^{2}) + 2*p*_{2}*xy*]

where:

*x*,*y*= undistorted pixel locations*p*_{1},*p*_{2}= tangential distortion coefficients of the lens*r*^{2}=*x*^{2}+*y*^{2}

The undistorted pixel locations appear in normalized image coordinates, with the origin at the optical center. The coordinates are expressed in world units. `TangentialDistortionCoefficients`

is equivalent to the `TangentialDistortion`

(Computer Vision Toolbox) property of a `cameraIntrinsics`

object.

`Skew`

— Skew angle of camera axes

`0`

(default) | nonnegative real-valued scalar

Skew angle of camera axes, specified as a nonnegative real-valued scalar. If the *X*-axis and *Y*-axis are exactly perpendicular, then the skew must be `0`

. Units are dimensionless. `Skew`

is equivalent to the `Skew`

(Computer Vision Toolbox) property of a `cameraIntrinsics`

object.

`EnableDepthOutput`

— Option to enable depth output

`0`

or `false`

(default) | `1`

or `true`

Option to enable depth output, specified as `0`

(`false`

) if depth output is not enabled or `1`

(`true`

) if it is enabled.

**Example: **`EnableDepthOutput=1`

`EnableSemanticOutput`

— Option to enable semantic output

`0`

or `false`

(default) | `1`

or `true`

Option to enable semantic output, specified as `0`

(`false`

) if semantic output is not enabled or
`1`

(`true`

) if it is enabled.

**Example: **`EnableSemanticOutput=1`

## Properties

`Parent`

— Parent of actor

handle to parent actor object

Parent of actor, specified as a handle to the parent actor
object. After you add an actor to the `sim3d.World`

object, the default parent
actor is the `Scene Origin`

at `(0,0,0)`

. Use
`Parent`

to set any actor in the 3D environment as the parent actor of a
`sim3d.sensors.Camera`

object.

`Children`

— Children of actor

structure

This property is read-only.

Children of actor, specified as a structure. Each field of the structure contains a handle to
the child of a `sim3d.sensors.Camera`

object.

`ParentWorld`

— Parent world

handle to parent world object

Parent world, specified as a handle to the parent `sim3d.World`

object. You can use this property only if the `sim3d.sensors.Camera`

object is
added to the parent `sim3d.World`

object.

`SensorIdentifier`

— Unique ID of sensor

real positive scalar

This property is read-only.

Unique ID of the sensor, specified as a real positive scalar.

**Data Types: **`uint32`

`Translation`

— Relative translation

`[0,0,0]`

(default) | real 1-by-3 vector

Relative translation
(*x*,*y*,*z*) of the actor object to its
parent actor, specified as a real 1-by-3 vector, in m. Use `Translation`

to
change the position of the `sim3d.sensors.Camera`

object in the 3D environment along the
*X*, *Y*, and *Z* axes of the
coordinate system. When you add an actor to the 3D environment, the default parent actor is the
`Scene Origin`

at `(0,0,0)`

.

**Example: **`camera.Translation = [1 2 1]`

`Rotation`

— Relative rotation

`[0,0,0]`

(default) | real 1-by-3 vector

Relative rotation (*roll*,
*pitch*, *yaw*) of the actor object to its parent actor,
specified as a real 1-by-3 vector, in rad. Use `Rotation`

to rotate the
`sim3d.sensors.Camera`

object in the 3D environment.

**Example: **`camera.Rotation = [pi/4 pi/8 pi/2]`

`Mobility`

— Type of actor mobility

`'sim3d.utils.MobilityTypes.Static'`

(default) | `'sim3d.utils.MobilityTypes.Movable'`

Type of actor mobility to respond to physics, move the actor
during simulation, or both, specified as `'sim3d.utils.MobilityTypes.Movable'`

or `'sim3d.utils.MobilityTypes.Static'`

.

**Example: **```
camera.Mobility =
sim3d.utils.MobilityTypes.Movable
```

**Data Types: **`sim3d.utils.MobilityTypes`

`FocalLength`

— Focal length of camera

`[1109,1109]`

(default) | real-valued 1-by-2 vector of positive integers

Focal length of camera, specified as a real-valued 1-by-2
vector of positive integers of the form [*fx*, *fy*], in pixels.

*fx* = *F* ×
*sx*

*fy* = *F* ×
*sy*

where:

*F*is the focal length in world units, typically millimeters.[

*sx*,*sy*] are the number of pixels per world unit in the*x*and*y*direction, respectively.

`FocalLength`

is equivalent to the `FocalLength`

(Computer Vision Toolbox) property
of a `cameraIntrinsics`

object.

`OpticalCenter`

— Optical center of camera

`[640,360]`

(default) | real-valued 1-by-2 vector of positive integers

Optical center of camera, specified as a real-valued 1-by-2
vector of positive integers of the form [*cx*,*cy*], in
pixels. `OpticalCenter`

is equivalent to the `PrincipalPoint`

(Computer Vision Toolbox)
property of a `cameraIntrinsics`

object.

`ImageSize`

— Image size produced by camera

`[768,1024]`

(default) | real-valued 1-by-2 vector of positive integers

Image size produced by the `sim3d.sensors.Camera`

object, specified as a real-valued 1-by-2 vector of positive integers of the form
[*m*,*n*], in pixels. `ImageSize`

is
equivalent to the `ImageSize`

(Computer Vision Toolbox) property of a
`cameraIntrinsics`

object.

`RadialDistortionCoefficients`

— Radial distortion coefficients

`[0,0]`

(default) | real-valued 2-element vector | real-valued 3-element vector | real-valued 6-element vector

Radial distortion coefficients, specified as a real-valued 2-element, 3-element, or 6-element vector. Radial distortion is the displacement of image points along radial lines extending from the principal point.

As the image points move away from the principal point (positive radial displacement), image magnification decreases, and a pincushion-shaped distortion occurs on the image.

As the image points move toward the principal point (negative radial displacement), image magnification increases, and a barrel-shaped distortion occurs on the image.

The camera sensor calculates the
(*x*_{d},*y*_{d})
radial-distorted location of a point using a two-coefficient, three-coefficient, or
six-coefficient formula. This table shows the formulas, where:

(

*x*,*y*) = undistorted pixel locations*k*_{1},*k*_{2},*k*_{3},*k*_{4},*k*_{5},*k*_{6}= radial distortion coefficients of the lens*r*^{2}=*x*^{2}+*y*^{2}

Coefficients | Formula | Description |

`[k1, k2]` |
| This model is equivalent to the two-coefficient model used by the
`RadialDistortion` (Computer Vision Toolbox) property of a
`cameraIntrinsics` object. |

`[k1, k2, k3]` |
| This model is equivalent to the three-coefficient model used by the
`RadialDistortion` (Computer Vision Toolbox) property of a
`cameraIntrinsics` object. |

`[k1, k2, k3, k4, k5, k6]` | $$\begin{array}{l}{x}_{\text{d}}=x\times \frac{1+{k}_{1}{r}^{2}+\text{}{k}_{2}{r}^{4}+{k}_{3}{r}^{6}}{1+{k}_{4}{r}^{2}+{k}_{5}{r}^{4}+{k}_{6}{r}^{6}}\\ {y}_{\text{d}}=y\times \frac{1+{k}_{1}{r}^{2}+\text{}{k}_{2}{r}^{4}+{k}_{3}{r}^{6}}{1+{k}_{4}{r}^{2}+{k}_{5}{r}^{4}+{k}_{6}{r}^{6}}\end{array}$$ | The six-coefficient model is based on the OpenCV radial distortion model.
The Camera Calibrator app does not support this model. To calibrate a camera using this model, see Camera Calibration and 3D Reconstruction in the OpenCV documentation. |

`TangentialDistortionCoefficients`

— Tangential distortion coefficients

`[0,0]`

(default) | real-valued 2-element vector

Tangential distortion coefficients, specified as a real-valued 2-element vector. Tangential distortion occurs when the lens and the image plane are not parallel.

The camera sensor calculates the tangential distorted location of a point, (*x*_{d}, *y*_{d}), using this formula:

*x*_{d} = *x* + [2*p*_{1}*xy* + *p*_{2} × (*r*^{2} + 2*x*^{2})]

*y*_{d} = *y* + [*p*_{1} × (*r*^{2} + 2*y*^{2}) + 2*p*_{2}*xy*]

where:

*x*,*y*= undistorted pixel locations*p*_{1},*p*_{2}= tangential distortion coefficients of the lens*r*^{2}=*x*^{2}+*y*^{2}

The undistorted pixel locations appear in normalized image coordinates, with the origin at the optical center. The coordinates are expressed in world units. `TangentialDistortionCoefficients`

is equivalent to the `TangentialDistortion`

(Computer Vision Toolbox) property of a `cameraIntrinsics`

object.

`Skew`

— Skew angle of camera axes

`0`

(default) | nonnegative real-valued scalar

Skew angle of camera axes, specified as a nonnegative real-valued scalar. If the *X*-axis and *Y*-axis are exactly perpendicular, then the skew must be `0`

. Units are dimensionless. `Skew`

is equivalent to the `Skew`

(Computer Vision Toolbox) property of a `cameraIntrinsics`

object.

## Object Functions

`read` | Return image data captured with camera |

## Algorithms

### Camera Model

The `sim3d.sensors.Camera`

object uses the camera model proposed by Jean-Yves
Bouguet [1]. The model includes:

The pinhole camera model does not account for lens distortion because an ideal pinhole camera does not have a lens. To accurately represent a real camera, the full camera model used by the object includes radial and tangential lens distortion.

For more details, see What Is Camera Calibration? (Computer Vision Toolbox)

## References

[1] Bouguet, Jean-Yves.
*Camera Calibration Toolbox for Matlab*. CaltechDATA, 2022.
https://doi.org/10.22002/D1.20164.

[2] Zhang, Zhengyou. "A Flexible New
Technique for Camera Calibration." *IEEE Transactions on Pattern Analysis and
Machine Intelligence*. 22, no. 11 (2000): 1330–34.

[3] Heikkilä, Janne, and Olli Silven.
“A Four-Step Camera Calibration Procedure with Implicit Image Correction.” In
*Proceedings of IEEE International Conference on Computer Vision and Pattern
Recognition*. San Juan, PR, June 17–19, 1997: 1106–12.
https://doi.org/10.1109/CVPR.1997.609468.

## Version History

**Introduced in R2024b**

## MATLAB 명령

다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.

명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)