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:

• Create a geocrs object, and then query its Spheroid property.

• Create a projcrs object, access the geocrs object contained in its GeographicCRS property, and then query the Spheroid property of the geocrs.

• Use the referenceSphere function (described here).

Syntax

S = referenceSphere

S = referenceSphere(name)

S = referenceSphere(name,lengthUnit)

Description

S = referenceSphere creates a referenceSphere object that represents the unit sphere.

S = referenceSphere(name) creates a referenceSphere object corresponding to the specified spherical body given by name. The radius of the reference sphere is in meters.

S = referenceSphere(name,lengthUnit) creates a 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

Read-only: 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

Read-only: 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

Read-only: Inf (default)

This property is read-only.

Reciprocal of flattening, specified as the value Inf.

Data Types: double

Eccentricity — First eccentricity of sphere

Read-only: 0 (default)

This property is read-only.

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

Data Types: double

Flattening — Flattening of sphere

Read-only: 0 (default)

This property is read-only.

Flattening of the sphere, specified as the value 0.

Data Types: double

ThirdFlattening — Third flattening of sphere

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: 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