# referenceSphere

Reference sphere

## Description

A `referenceSphere`

object represents a sphere with a
specific name and radius that you can use in map projections and other geodetic
operations.

## Creation

There are several ways to create reference sphere objects, including:

### Description

`S = referenceSphere`

creates a
`referenceSphere`

object that represents the unit
sphere.

`S = referenceSphere(`

creates a
`name`

)`referenceSphere`

object corresponding to the specified
spherical body given by `name`

. The radius of the reference
sphere is in meters.

`S = referenceSphere(`

creates a `name`

,`lengthUnit`

)`referenceSphere`

object with radius in the specified
unit of length, `LengthUnit`

. The unit of length can be any
length unit supported by the `validateLengthUnit`

function.

### Input Arguments

`name`

— Name of predefined reference sphere

`'Unit Sphere'`

(default) | `'earth'`

| `'sun'`

| `'moon'`

| ...

Name of predefined reference sphere, specified as
`'earth'`

, `'sun'`

,
`'moon'`

, `'mercury'`

,
`'venus'`

, `'mars'`

,
`'jupiter'`

, `'saturn'`

,
`'uranus'`

, `'neptune'`

,
`'pluto'`

, or `'unit sphere'`

. The
`name`

argument is not case-sensitive.

**Data Types: **`char`

| `string`

`lengthUnit`

— Length unit

`''`

(default) | character vector | string scalar

Length unit, specified as a character vector or string scalar. You can
specify any length unit that is supported by the `validateLengthUnit`

function.

Value | Unit Name |
---|---|

`"m"` , `"meter"` ,
`"meters"` , `"metre"` ,
`"metres"` | Meters |

`"cm"` , `"centimeter"` ,
`"centimeters"` , `"centimetre"` ,
`"centimetres"` | Centimeters |

`"mm"` , `"millimeter"` ,
`"millimeters"` , `"millimetre"` ,
`"millimetres"` | Millimeters |

`"micron"` , `"microns"` | Microns |

`"km"` ,` "kilometer"` ,
`"kilometers"` , `"kilometre"` ,
`"kilometers"` | Kilometers |

`"nm"` , `"naut mi"` , ```
"nautical
mile"
``` , `"nautical miles"` | Nautical miles |

`"ft"` , `"international ft"` ,
`"foot"` , `"international foot"` ,
`"feet"` , `"international feet"` | Feet |

`"in"` , `"inch"` ,
`"inches"` | Inches |

`"yd"` , `"yds"` , `"yard"` ,
`"yards"` | Yards |

`"mi"` , `"mile"` ,
`"miles"` , `"international mile"` ,
`"international miles"` | Miles |

`"sf"` , `"survey ft"` , ```
"US survey
ft"
``` , `"U.S. survey ft"` , ```
"survey
foot"
``` , `"US survey foot"` , ```
"U.S. survey
foot"
``` , `"survey feet"` , ```
"US survey
feet"
``` , `"U.S. survey feet"` | U.S. survey feet |

`"sm"` , `"survey mile"` , ```
"survey
miles"
``` , `"statute mile"` , ```
"statute
miles"
``` , `"US survey mile"` , ```
"US survey
miles"
``` , `"U.S. survey mile(s)"` , ```
"U.S.
survey miles"
``` | U.S. survey miles (statute miles) |

`"Clarke's foot"` , `"Clarkes foot"` | Clarke's feet |

`"German legal metre"` , ```
"German legal
meter"
``` | German legal metres |

`"Indian foot"` | Indian feet |

**Data Types: **`char`

| `string`

## Properties

`Name`

— Name of reference sphere

`'Unit Sphere'`

(default) | character vector | string scalar

Name of the reference sphere, specified as a string scalar or character vector.

**Example: **`'Sun'`

**Data Types: **`char`

| `string`

`LengthUnit`

— Unit of length of the radius

`''`

(default) | character vector | string scalar

Unit of length of the radius, specified as a string scalar or character
vector. You can specify any unit of length accepted by the `validateLengthUnit`

function.
When the reference sphere represents the unit sphere,
`LengthUnit`

is the empty character vector ```
'
'
```

.

**Example: **`'km'`

**Data Types: **`char`

| `string`

`Radius`

— Radius of the sphere

positive, finite scalar

Radius of the sphere, specified as positive, finite scalar.

**Data Types: **`double`

`SemimajorAxis`

— Equatorial radius of the sphere

1 (default) | positive, finite scalar

This property is read-only.

Equatorial radius of the sphere, specified as a positive, finite scalar.
The value of `SemimajorAxis`

is equal to the value of
`Radius`

.

**Data Types: **`double`

`SemiminorAxis`

— Distance from center of sphere to pole

1 (default) | positive, finite scalar

This property is read-only.

Distance from center of sphere to pole, specified as a positive, finite
scalar. The value of `SemiminorAxis`

is equal to the
value of `Radius`

.

**Data Types: **`double`

`InverseFlattening`

— Reciprocal of flattening

`Inf`

(default)

This property is read-only.

Reciprocal of flattening, specified as the value
`Inf`

.

**Data Types: **`double`

`Eccentricity`

— First eccentricity of sphere

0 (default)

This property is read-only.

First eccentricity of the sphere, specified as the value 0.

**Data Types: **`double`

`Flattening`

— Flattening of sphere

0 (default)

This property is read-only.

Flattening of the sphere, specified as the value 0.

**Data Types: **`double`

`ThirdFlattening`

— Third flattening of sphere

0 (default)

This property is read-only.

Third flattening of the sphere, specified as the value 0.

**Data Types: **`double`

`MeanRadius`

— Mean radius of the sphere

positive, finite scalar

This property is read-only.

Mean radius of the sphere, specified as positive, finite scalar. The value
of `MeanRadius`

is equal to the value of
`Radius`

.

**Data Types: **`double`

`SurfaceArea`

— Surface area of the sphere

positive, finite scalar

This property is read-only.

Surface area of the sphere, specified as positive, finite scalar.

The `SurfaceArea`

property is expressed in units of
area consistent with the unit of length specified by the
`LengthUnit`

property.

**Data Types: **`double`

`Volume`

— Volume of the sphere

positive, finite scalar

This property is read-only.

Volume of the sphere, specified as positive, finite scalar.

The `Volume`

property is expressed in units of volume
consistent with the unit of length specified by the
`LengthUnit`

property.

**Data Types: **`double`

## Examples

### Create Model of Earth in Kilometers

Construct a reference sphere that models the Earth as a sphere with a radius of 6371000 meters. Note that the unit of length is meters.

```
s = referenceSphere('Earth')
```

s = referenceSphere with defining properties: Name: 'Earth' LengthUnit: 'meter' Radius: 6371000 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume

Switch the unit of length in the reference sphere to kilometers.

`s.LengthUnit = 'kilometer'`

s = referenceSphere with defining properties: Name: 'Earth' LengthUnit: 'kilometer' Radius: 6371 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume

Determine the surface area of the sphere in square kilometers.

s.SurfaceArea

ans = 5.1006e+08

Find the volume of the sphere in cubic kilometers.

s.Volume

ans = 1.0832e+12

### Create Custom Model for Planet

Create a custom reference sphere for a planet by modifying the properties of a default reference sphere.

customPlanet = referenceSphere; customPlanet.Name = 'Tiny Planet'; customPlanet.LengthUnit = 'meter'; customPlanet.Radius = 8000

customPlanet = referenceSphere with defining properties: Name: 'Tiny Planet' LengthUnit: 'meter' Radius: 8000 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume

### Get Reference Sphere from Coordinate Reference System

Create a geographic CRS for the moon, which has the ESRI code `104903`

. Then, get the reference sphere by querying the `Spheroid`

property of the geographic CRS.

gcrs1 = geocrs(104903,"Authority","ESRI"); S1 = gcrs1.Spheroid

S1 = referenceSphere with defining properties: Name: 'Moon_2000_IAU_IAG' LengthUnit: 'meter' Radius: 1737400 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume

## Version History

**Introduced in R2012a**

## See Also

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## 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)