Skip to main content
`Ctrl`+`K`

# UnitSphericalRepresentation

class astropy.coordinates.UnitSphericalRepresentation(lon, lat=None, differentials=None, copy=True)

  Bases: `BaseRepresentation`

  Representation of points on a unit sphere.

  Parameters:
    lon, lat `Quantity` [:ref: ‘angle’] or `python:str`

      The longitude and latitude of the point(s), in angular units. The latitude should be between -90 and 90 degrees, and the longitude will be wrapped to an angle between 0 and 360 degrees. These can also be instances of `Angle`, `Longitude`, or `Latitude`.

    differentials `python:dict`, `BaseDifferential`, optional

      Any differential classes that should be associated with this representation. The input must either be a single `BaseDifferential` instance (see `_compatible_differentials` for valid types), or a dictionary of of differential instances with keys set to a string representation of the SI unit with which the differential (derivative) is taken. For example, for a velocity differential on a positional representation, the key would be `'s'` for seconds, indicating that the derivative is a time derivative.

    copy bool, optional

      If `True` (default), arrays will be copied. If `False`, arrays will be references, though possibly broadcast to ensure matching shapes.

  Attributes Summary

  `attr_classes` |
  `lat` | The latitude of the point(s).
  `lon` | The longitude of the point(s).
  `name` | Name of the representation or differential.

  Methods Summary

  `cross`(other) | Cross product of two representations.
  `from_cartesian`(cart) | Converts 3D rectangular cartesian coordinates to spherical polar coordinates.
  `mean`(*args, **kwargs) | Vector mean.
  `norm`() | Vector norm.
  `represent_as`(other_class[, differential_class]) | Convert coordinates to another representation.
  `scale_factors`([omit_coslat]) | Scale factors for each component's direction.
  `sum`(*args, **kwargs) | Vector sum.
  `to_cartesian`() | Converts spherical polar coordinates to 3D rectangular cartesian coordinates.
  `transform`(matrix) | Transform the unit-spherical coordinates using a 3x3 matrix.
  `unit_vectors`() | Cartesian unit vectors in the direction of each component.

  Attributes Documentation

  attr_classes = {'lat': <class 'astropy.coordinates.angles.core.Latitude'>, 'lon': <class 'astropy.coordinates.angles.core.Longitude'>}
  lat

    The latitude of the point(s).

  lon

    The longitude of the point(s).

  name = 'unitspherical'

    Name of the representation or differential.

    When a subclass is defined, by default, the name is the lower-cased name of the class with with any trailing ‘representation’ or ‘differential’ removed. (E.g., ‘spherical’ for `SphericalRepresentation` or `SphericalDifferential`.)

    This can be customized when defining a subclass by setting the class attribute.

  Methods Documentation

  cross(other)

    Cross product of two representations.

    The calculation is done by converting both `self` and `other` to `CartesianRepresentation`, and converting the result back to `SphericalRepresentation`.

    Parameters:
      other `BaseRepresentation` subclass instance

        The representation to take the cross product with.

    Returns:
      cross_product `SphericalRepresentation`

        With vectors perpendicular to both `self` and `other`.

  classmethod from_cartesian(cart)

    Converts 3D rectangular cartesian coordinates to spherical polar coordinates.

  mean(*args, **kwargs)

    Vector mean.

    The representation is converted to cartesian, the means of the x, y, and z components are calculated, and the result is converted to a `SphericalRepresentation`.

    Refer to `mean` for full documentation of the arguments, noting that `axis` is the entry in the `shape` of the representation, and that the `out` argument cannot be used.

  norm()

    Vector norm.

    The norm is the standard Frobenius norm, i.e., the square root of the sum of the squares of all components with non-angular units, which is always unity for vectors on the unit sphere.

    Returns:
      norm `Quantity` [:ref: ‘dimensionless’]

        Dimensionless ones, with the same shape as the representation.

  represent_as(other_class, differential_class=None)

    Convert coordinates to another representation.

    If the instance is of the requested class, it is returned unmodified. By default, conversion is done via Cartesian coordinates. Also note that orientation information at the origin is not preserved by conversions through Cartesian coordinates. See the docstring for `to_cartesian()` for an example.

    Parameters:
      other_class `BaseRepresentation` subclass

        The type of representation to turn the coordinates into.

      differential_class `python:dict` of `BaseDifferential`, optional

        Classes in which the differentials should be represented. Can be a single class if only a single differential is attached, otherwise it should be a `dict` keyed by the same keys as the differentials.

  scale_factors(omit_coslat=False)

    Scale factors for each component’s direction.

    Given unit vectors \(\hat{e}_c\) and scale factors \(f_c\), a change in one component of \(\delta c\) corresponds to a change in representation of \(\delta c \times f_c \times \hat{e}_c\).

    Returns:
      scale_factors `python:dict` of `Quantity`

        The keys are the component names.

  sum(*args, **kwargs)

    Vector sum.

    The representation is converted to cartesian, the sums of the x, y, and z components are calculated, and the result is converted to a `SphericalRepresentation`.

    Refer to `sum` for full documentation of the arguments, noting that `axis` is the entry in the `shape` of the representation, and that the `out` argument cannot be used.

  to_cartesian()

    Converts spherical polar coordinates to 3D rectangular cartesian coordinates.

  transform(matrix)

    Transform the unit-spherical coordinates using a 3x3 matrix.

    This returns a new representation and does not modify the original one. Any differentials attached to this representation will also be transformed.

    Parameters:
      matrix(3,3) numpy:array_like

        A 3x3 matrix, such as a rotation matrix (or a stack of matrices).

    Returns:
      `UnitSphericalRepresentation` or `SphericalRepresentation`

        If `matrix` is O(3) – \(M \dot M^T = I\) – like a rotation, then the result is a `UnitSphericalRepresentation`. All other matrices will change the distance, so the dimensional representation is used instead.

  unit_vectors()

    Cartesian unit vectors in the direction of each component.

    Given unit vectors \(\hat{e}_c\) and scale factors \(f_c\), a change in one component of \(\delta c\) corresponds to a change in representation of \(\delta c \times f_c \times \hat{e}_c\).

    Returns:
      unit_vectors `python:dict` of `CartesianRepresentation`

        The keys are the component names.