Main Content

referenceSphere

Reference sphere

expand all in page

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.

example

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.

example

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

expand all

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

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

ValueUnit 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

expand all

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

Example: 'Sun'

Data Types: char | string

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 of the sphere, specified as positive, finite scalar.

Data Types: double

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

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

This property is read-only.

Reciprocal of flattening, specified as the value Inf.

Data Types: double

This property is read-only.

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

Data Types: double

This property is read-only.

Flattening of the sphere, specified as the value 0.

Data Types: double

This property is read-only.

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

Data Types: double

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

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

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

collapse all

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 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
Open Live Script

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

| |