# CustomSurface

## Description

`CustomSurface`

defines a custom surface object belonging to a radar
scenario, `radarScenario`

. The
object describes the extent and complex scattering response of the surface. You can use the
`CustomSurface`

object to update polarization scattering matrices, determine
surface heights, and test for occlusion. `CustomSurface`

objects are compatible with I/Q sensors generated by `radarTransceiver`

and
require that the scenario sensor, surface, and targets are polarized. Scattering matrices are
specific to a single frequency and viewing geometry and are therefore relevant to a single
sensor attached to the `radarScenario`

. Effects due to occlusion should be
modeled within the surface scattering matrix.

## Creation

Create `CustomSurface`

objects using the `customSurface`

object function of the `radarScenario`

object.

## Properties

`Boundary`

— Bounding rectangle of surface (degrees)

[-60 60; -60 60] (default) | finite 2-by-2 matrix

Extent of the rectangular custom surface, specified as a 2-by-2 finite matrix in units
of degrees. The bounding rectangle is defined by two 2-dimensional points in either
Cartesian or geodetic scenario coordinates. When the
`IsEarthCentered`

property of the `radarScenario`

object is specified as:

`false`

— Scenario coordinates are Cartesian. Specify the bounding rectangle as [`minX`

,`maxX`

,`minY`

`maxY`

].`minX`

and`maxX`

are the minimum and maximum values in the*x*-direction of the reference frame, where`minX`

<`maxX`

.`minY`

and`maxY`

are the minimum and maximum values in the*y*-direction of the reference frame, where`minY`

<`maxY`

.`true`

— Scenario coordinates are geodetic. Specify the bounding rectangle as [`startLat`

,`endLat`

,`startLon`

`endLon`

].`startLat`

and`endLat`

are the minimum and maximum latitudes of the geodetic frames, where`startLat`

and`endLat`

must lie in the interval [–90,90] and`startLat`

<`endLat`

.`startLon`

and`endLon`

are the minimum and maximum longitudes of the geodetic frame and must lie in the interval [–180,180]. If`endLon`

<`startLon`

, the object wraps`endLon`

to`startLon`

+`360°`

. Units are in degrees.

The resolution of surface patches within `Boundary`

is
given by `resX`

= `lengthX`

/
`numX`

for the *x*-dimension. Similarly, the resolution
for the *y*-dimension is `resY`

= `lengthY`

/
`numY`

. `lengthX`

and `lengthY`

are
calculated as the differences of the `Boundary`

coordinates in the
*x*- and *y*- dimensions, respectively. The
number of surface patches within the boundary is determined by the size of the
scattering matrix component `Shh`

. For the
*x*-dimension, `numX`

=
`size`

(`Shh`

,`1`

) and for the *y*-dimension, `numY`

=
`size`

(`Shh`

,`2`

). Note, the `clutterGenerator`

`Resolution`

property for the `radarScenario`

should
match the resolution of the custom surface to prevent resampling of the surface. For
example, if you have a surface that is 500-by-1 km in Cartesian space with a
`clutterGenerator`

`Resolution`

set to 50 m, the `Boundary`

could be
specified as `[–200 300; 100 1100]`

. For this case, the polarization
scattering matrix components (`Shh`

, `Svv`

,
`Shv`

, and `Svh`

) should be of size 20-by-10 m
because `numX`

= (`maxX`

–
`minX`

) / `resX`

, and `numY`

= (`maxY`

–
`minY`

) / `resY`

.

**Data Types: **`double`

`CrossPolarization`

— Polarization scattering matrix type

`"full"`

(default) | `"symmetric"`

Specify the polarization scattering matrix as either `full`

or
`symmetric`

. If `CrossPolarization`

is
`full`

, the polarization matrix components
`Shh`

, `Svv`

, `Shv`

, and
`Svh`

must all be specified. If
`CrossPolarization`

is set to `symmetric`

,
reciprocity is assumed (monostatic geometry), and the cross-polarization terms are
considered to be equivalent (`Shv`

= `Svh`

).
Therefore, `Shv`

is automatically set to the same value as
`Svh`

and cannot be modified.

**Data Types: **`char`

| `string`

`Shh`

— Polarization scattering matrix co-polarized `HH`

component

3-by-3-by-2 matrix of ones (default) | `M`

-by-`N`

-by-`P`

matrix

Specify the complex-valued polarization scattering matrix co-polarized
`HH`

component, where `HH`

represents horizontal
transmission and horizontal reception, as an
`M`

-by-`N`

-by-`P`

matrix.
`M`

indicates the number of components in the
*x*-direction, `N`

indicates the number of
components in the *y*-direction, and `P`

corresponds
to the number of elements in the `Frequency`

vector. The matrix is
bounded in space by the `Boundary`

property limits.

**Data Types: **`double`

**Complex Number Support: **Yes

`Svv`

— Polarization scattering matrix co-polarized `VV`

component

3-by-3-by-2 matrix of ones (default) | `M`

-by-`N`

-by-`P`

matrix

Specify the complex-valued polarization scattering matrix co-polarized
`VV`

component, where `VV`

represents vertical
transmission and vertical reception, as an
`M`

-by-`N`

-by-`P`

matrix.
`M`

indicates the number of components in the
*x*-direction, `N`

indicates the number of
components in the *y*-direction, and `P`

corresponds
to the number of elements in the `Frequency`

vector. The matrix is
bounded in space by the `Boundary`

property limits.

**Data Types: **`double`

**Complex Number Support: **Yes

`Shv`

— Polarization scattering matrix cross-polarized `HV`

component

3-by-3-by-2 matrix of ones (default) | `M`

-by-`N`

-by-`P`

matrix

Specify the complex-valued polarization scattering matrix cross-polarized
`HV`

component, where `HV`

represents horizontal
transmission and vertical reception, as an
`M`

-by-`N`

-by-`P`

matrix.
`M`

indicates the number of components in the
*x*-direction, `N`

indicates the number of
components in the *y*-direction, and `P`

corresponds
to the number of elements in the `Frequency`

vector. The matrix is
bounded in space by the `Boundary`

property limits.

**Data Types: **`double`

**Complex Number Support: **Yes

`Svh`

— Polarization scattering matrix cross-polarized `VH`

component

3-by-3-by-2 matrix of ones (default) | `M`

-by-`N`

-by-`P`

matrix

Specify the complex-valued polarization scattering matrix cross-polarized
`VH`

component, where `VH`

represents vertical
transmission and horizontal reception, as an
`M`

-by-`N`

-by-`P`

matrix.
`M`

indicates the number of components in the
*x*-direction, `N`

indicates the number of
components in the *y*-direction, and `P`

corresponds
to the number of frequencies in `Frequency`

. The matrix is bounded in
space by the `Boundary`

property limits.

#### Dependencies

To enable this property, set the `CrossPolarization`

property
to `"full"`

.

**Data Types: **`double`

**Complex Number Support: **Yes

`Frequency`

— Frequencies for the scattering matrix (Hz)

[0 1e20] (default) | length-`P`

row vector

Valid frequencies for the scattering matrix components
specified as a length-`P`

row
vector, where `P`

is the number of
frequencies. Frequency units are in hertz
(Hz).

**Data Types: **`double`

`ReferenceHeight`

— Surface reference height (m)

0 (default) | scalar

Reference height of surface height data, specified as a scalar. Surface heights are relative to the reference height. Units are in meters.

**Data Types: **`double`

## Object Functions

`updateScatteringMatrix` | Update scattering matrices |

`height` | Height of point on surface |

`occlusion` | Test for occlusion of point by a surface |

## Examples

### Create Co-Polarized and Cross-Polarized Custom Surfaces

This example shows how to create a custom surface and update the polarization scattering matrices. Co-polarized and cross-polarized surfaces are compared.

**Create Custom Surface**

Create a co-polarized custom surface.

% Create a radar scenario rng('default'); scenario = radarScenario(IsEarthCentered=false); % Create a co-polarized custom surface bnds = [-600 570; 0 1.17e3]; Shh = zeros(40,40,2); Svv = ones(40,40,2); Shv = zeros(size(Shh)); srf = customSurface(scenario,Boundary=bnds, ... CrossPolarization='symmetric',Shh=Shh,Svv=Svv,Shv=Shv);

**Collect I/Q Data**

Create a vertically polarized radar I/Q sensor and collect data.

% Create a vertically polarized radar IQ sensor and attach to % a platform freq = 500e6; sweepBW = 5e6; fs = 2*sweepBW; wav = phased.LinearFMWaveform(SampleRate=fs, ... SweepBandwidth=sweepBW); rdr = radarTransceiver(Waveform=wav, ... MountingAngles=[-90 10 0], ... RangeLimits=[0 1.2e3]); element = phased.ShortDipoleAntennaElement; ula = phased.ULA(Element=element); configureAntennas(rdr,Combined=ula); rdr.TransmitAntenna.OperatingFrequency = freq; rdr.ReceiveAntenna.OperatingFrequency = freq; rdr.Receiver.SampleRate = fs; rdrplat = platform(scenario,Position=[0 0 10],Sensors=rdr); % Create clutter generator cluttergen = clutterGenerator(scenario,rdr,Resolution=30, ... RangeLimit=1.2e3); % Advance scenario and collect IQ advance(scenario); iq = receive(scenario); % Pulse compress mf = getMatchedFilter(rdr.Waveform); rngresp = phased.RangeResponse(SampleRate=fs); [iqPC,rngGrid] = rngresp(iq{1}(:,1),mf); figure nexttile plot(rngGrid,mag2db(abs(iqPC))) title(['Pulse 1, Element 1' newline 'Co-Polarized Surface']) xlabel('Range (m)') ylabel('Magnitude (dB)') grid on axis tight ylim([-80 60])

**Update Scattering Matrix Values**

Update scattering matrix values for HH and VV components to make the surface cross-polarized and collect I/Q data.

% Update scattering matrix values for HH and VV components. % Make the surface cross-polarized. Shh = ones(40,40,2); Svv = zeros(40,40,2); updateScatteringMatrix(srf,Shh=Shh,Svv=Svv) % Collect IQ iq = receive(scenario); [iqPC,rngGrid] = rngresp(iq{1}(:,1),mf); nexttile plot(rngGrid,mag2db(abs(iqPC))) title(['Pulse 2, Element 1' newline ... 'Cross-Polarized Surface']) xlabel('Range (m)') ylabel('Magnitude (dB)') grid on axis tight ylim([-80 60])

## Version History

**Introduced in R2024a**

## See Also

`customSurface`

| `SurfaceManager`

| `radarScenario`

| `landSurface`

| `seaSurface`

| `clutterGenerator`

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

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)