Helioprojective#

class sunpy.coordinates.Helioprojective(*args, **kwargs)[source]#

Bases: SunPyBaseCoordinateFrame

A coordinate or frame in the Helioprojective Cartesian (HPC) system.

This is an observer-based spherical coordinate system, with:

The origin is the observer location.
The line connecting the poles of the frame is parallel to the component of the Sun’s rotation axis that is perpendicular to the observer-Sun line.
Tx (short for “theta_x”, or \(\theta_x\)) is the longitude, the angle relative to the plane containing the observer-Sun line and the poles of the frame, with positive values in the direction of the Sun’s west limb.
Ty (short for “theta_y”, or \(\theta_y\)) is the latitude, the angle relative to the plane that is perpendicular to the poles of the frame, with positive values in the direction of the Sun’s north pole.
distance is the observer-object distance.

Note

It can be confusing that the name of this coordinate system uses the adjective “Cartesian” despite being a spherical coordinate system. The reason for this name is because close to the center of the Sun where the small-angle approximation is appropriate, Tx and Ty can be thought of as two components of a Cartesian-like coordinate system. The corresponding third Cartesian-like component, sometimes called zeta (\(\zeta\)), is defined to be the Sun-observer distance (observer.radius) minus the observer-object distance (distance).

This system is frequently used in a projective form without distance specified. When transforming such a 2D coordinate to another frame, the object location usually needs to be fully 3D, which is achieved by calling make_3d() to generate the distance component. The default assumption is that the object lies on the surface of the Sun if the 2D coordinate is on the solar disk, but is otherwise undefined if the 2D coordinate is beyond the solar limb. This assumption can be modified using a screen (e.g., SphericalScreen()).

A new instance can be created using the following signatures (note that if supplied, obstime and observer must be keyword arguments):

Helioprojective(Tx, Ty, obstime=obstime, observer=observer)
Helioprojective(Tx, Ty, distance, obstime=obstime, observer=observer)

Parameters:

data (BaseRepresentation or None) – A representation object or None to have no data (or use the coordinate component arguments, see below).
Tx (Angle or Quantity) – The theta_x (\(\theta_x\)) component for this object. Not needed if data is given.
Ty (Angle or Quantity) – The theta_y (\(\theta_y\)) component for this object. Not needed if data is given.
distance (Quantity) – The distance component from the observer for this object. Not needed if data is given.
observer (HeliographicStonyhurst, str) – The location of the observer. If a string is provided, it must be a solar system body that can be parsed by get_body_heliographic_stonyhurst at the time obstime. Defaults to Earth center.
rsun (Quantity) – The radius of the Sun in length units. Used to convert a 2D coordinate (i.e., no radius component) to a 3D coordinate by assuming that the coordinate is on the surface of the Sun. Defaults to the photospheric radius as defined in sunpy.sun.constants.
obstime (tuple, list, str, pandas.Timestamp, pandas.Index, pandas.Series, pandas.DatetimeIndex, datetime.datetime, datetime.date, numpy.datetime64, numpy.ndarray, astropy.time.Time) – The time of the observation. This is used to determine the position of solar-system bodies (e.g., the Sun and the Earth) as needed to define the origin and orientation of the frame.
representation_type (BaseRepresentation, str, optional) – A representation class or string name of a representation class. This may change the valid coordinate component arguments from the defaults (see above). For example, passing representation_type='cartesian' will make the frame expect Cartesian coordinate component arguments (typically, x, y, and z).
copy (bool, optional) – If True (default), make copies of the input coordinate arrays.

Examples

>>> from astropy.coordinates import SkyCoord
>>> import sunpy.coordinates
>>> import astropy.units as u
>>> sc = SkyCoord(0*u.deg, 0*u.deg, 5*u.km,
...               obstime="2010/01/01T00:00:00", observer="earth", frame="helioprojective")
>>> sc
<SkyCoord (Helioprojective: obstime=2010-01-01T00:00:00.000, rsun=695700.0 km, observer=<HeliographicStonyhurst Coordinate for 'earth'>): (Tx, Ty, distance) in (arcsec, arcsec, km)
    (0., 0., 5.)>
>>> sc = SkyCoord(0*u.deg, 0*u.deg,
...               obstime="2010/01/01T00:00:00", observer="earth", frame="helioprojective")
>>> sc
<SkyCoord (Helioprojective: obstime=2010-01-01T00:00:00.000, rsun=695700.0 km, observer=<HeliographicStonyhurst Coordinate for 'earth'>): (Tx, Ty) in arcsec
    (0., 0.)>
>>> sc = SkyCoord(CartesianRepresentation(1*u.AU, 1e5*u.km, -2e5*u.km),
...               obstime="2011/01/05T00:00:50", observer="earth", frame="helioprojective")
>>> sc
<SkyCoord (Helioprojective: obstime=2011-01-05T00:00:50.000, rsun=695700.0 km, observer=<HeliographicStonyhurst Coordinate for 'earth'>): (Tx, Ty, distance) in (arcsec, arcsec, AU)
    (137.87948623, -275.75878762, 1.00000112)>

Attributes Summary

`angular_radius`	Angular radius of the Sun as seen by the observer.
`default_differential`	Default representation for differential data (e.g., velocity)
`default_representation`	Default representation for position data
`frame_attributes`
`frame_specific_representation_info`	Mapping for frame-specific component names
`name`
`observer`	A frame attribute
`rsun`	A frame attribute

Methods Summary

`is_visible`(*[, tolerance])	Returns whether the coordinate is on the visible side of the Sun.
`make_3d`()	This method calculates the third coordinate of the Helioprojective frame.

Attributes Documentation

angular_radius#

Angular radius of the Sun as seen by the observer.

The rsun frame attribute is the radius of the Sun in length units. The tangent vector from the observer to the edge of the Sun forms a right-angle triangle with the radius of the Sun as the far side and the Sun-observer distance as the hypotenuse. Thus, the sine of the angular radius of the Sun is ratio of these two distances.

default_differential#: Default representation for differential data (e.g., velocity)

default_representation#: Default representation for position data

frame_attributes = {'observer': <sunpy.coordinates.frameattributes.ObserverCoordinateAttribute object>, 'obstime': <sunpy.coordinates.frameattributes.TimeFrameAttributeSunPy object>, 'rsun': <astropy.coordinates.attributes.QuantityAttribute object>}#

frame_specific_representation_info#: Mapping for frame-specific component names

name = 'helioprojective'#

observer[source]#

A frame attribute

No default value

rsun#

A frame attribute

Default: 695700.0 km

Methods Documentation

is_visible(*, tolerance=<Quantity 1. m>)[source]#

Returns whether the coordinate is on the visible side of the Sun.

A coordinate is visible if it can been seen from the observer (the observer frame attribute) assuming that the Sun is an opaque sphere with a fixed radius (the rsun frame attribute). The visible side of the Sun is always smaller than a full hemisphere.

Parameters:: tolerance (Quantity) – The depth below the surface of the Sun that should be treated as transparent.

Notes

If the coordinate is 2D, it is automatically deemed visible. A 2D coordinate describes a look direction from the observer, who would simply see whatever is in “front”, and thus cannot correspond to a point hidden from the observer.

The tolerance parameter accommodates situations where the limitations of numerical precision would falsely conclude that a coordinate is not visible. For example, a coordinate that is expressly created to be on the solar surface may be calculated to be slightly below the surface, and hence not visible if there is no tolerance. However, a consequence of the tolerance parameter is that a coordinate that is formally on the far side of the Sun but is extremely close to the solar limb can be evaluated as visible. With the default tolerance value of 1 meter, a coordinate on the surface of the Sun can be up to 11 arcseconds of heliographic longitude past the solar limb and still be evaluated as visible.

Examples

>>> import numpy as np
>>> import astropy.units as u
>>> from astropy.coordinates import SkyCoord
>>> from sunpy.coordinates import HeliographicStonyhurst, Helioprojective

>>> hpc_frame = Helioprojective(observer='earth', obstime='2023-08-03')

>>> in_front = SkyCoord(0*u.arcsec, 0*u.arcsec, 0.5*u.AU, frame=hpc_frame)
>>> print(in_front.is_visible())
True

>>> behind = SkyCoord(0*u.arcsec, 0*u.arcsec, 1.5*u.AU, frame=hpc_frame)
>>> print(behind.is_visible())
False

>>> hgs_array = SkyCoord(np.arange(-180, 180, 60)*u.deg, [0]*6*u.deg,
...                      frame='heliographic_stonyhurst', obstime='2023-08-03')
>>> print(hgs_array)
<SkyCoord (HeliographicStonyhurst: obstime=2023-08-03T00:00:00.000, rsun=695700.0 km): (lon, lat) in deg
    [(-180., 0.), (-120., 0.), ( -60., 0.), (   0., 0.), (  60., 0.),
     ( 120., 0.)]>
>>> print(hgs_array.transform_to(hpc_frame).is_visible())
[False False  True  True  True False]

make_3d()[source]#

This method calculates the third coordinate of the Helioprojective frame. It assumes that the coordinate point is on the surface of the Sun.

If a point in the frame is off limb then NaN will be returned.

Returns:: new_frame (Helioprojective) – A new frame instance with all the attributes of the original but now with a third coordinate.