@@ -23,7 +23,7 @@ Frames without Data
2323Frame objects have two distinct (but related) uses. The first is
2424storing the information needed to uniquely define a frame (e.g.,
2525equinox, observation time). This information is stored on the frame
26- objects as (read-only) Python attributes, which are set with the object
26+ objects as (read-only) Python attributes, which are set when the object
2727is first created::
2828
2929 >>> from astropy.coordinates import ICRS, FK5
@@ -100,18 +100,23 @@ class::
100100 >>> icrs.representation
101101 <class 'astropy.coordinates.representation.SphericalRepresentation'>
102102 >>> icrs.representation_component_names
103- OrderedDict([(u'ra', u'lon'), (u'dec', u'lat'), (u'distance', u'distance')])
104-
105- The representation of the coordinate object can be changed, as shown
106- below. This actually does *nothing * to the object internal data which
107- stores the coordinate values, but it changes the external view of that
108- data in two ways: (1) the object prints itself in accord with the
109- new representation, and (2) the available attributes change to match
110- those of the new representation (e.g. from ``ra, dec, distance `` to
111- ``x, y, z ``). Setting the ``representation `` thus changes a *property *
112- of the object (how it appears) without changing the intrinsic object
113- itself which represents a point in 3d space.
114- ::
103+ OrderedDict([('ra', 'lon'), ('dec', 'lat'), ('distance', 'distance')])
104+
105+ One can get the data in a different representation if needed::
106+
107+ >>> icrs.represent_as('cartesian') # doctest: +FLOAT_CMP
108+ <CartesianRepresentation (x, y, z) [dimensionless]
109+ (0.99923861, 0.01744177, 0.0348995)>
110+
111+ The representation of the coordinate object can also be changed directly, as
112+ shown below. This actually does *nothing * to the object internal data which
113+ stores the coordinate values, but it changes the external view of that data in
114+ two ways: (1) the object prints itself in accord with the new representation,
115+ and (2) the available attributes change to match those of the new
116+ representation (e.g. from ``ra, dec, distance `` to ``x, y, z ``). Setting the
117+ ``representation `` thus changes a *property * of the object (how it appears)
118+ without changing the intrinsic object itself which represents a point in 3d
119+ space.::
115120
116121 >>> from astropy.coordinates import CartesianRepresentation
117122 >>> icrs.representation = CartesianRepresentation
@@ -167,8 +172,9 @@ if it is preset, it can be accessed from the ``data`` attribute::
167172 <UnitSphericalRepresentation (lon, lat) in deg
168173 (1.1, 2.2)>
169174
170- All of the above methods can also accept array data (or other Python
171- sequences) to create arrays of coordinates::
175+ All of the above methods can also accept array data (in the form of
176+ class:`~astropy.unit.Quantity `, or other Python sequences) to create arrays of
177+ coordinates::
172178
173179 >>> ICRS(ra=[1.5, 2.5]*u.deg, dec=[3.5, 4.5]*u.deg)
174180 <ICRS Coordinate: (ra, dec) in deg
@@ -181,15 +187,48 @@ over the scalars appropriately::
181187 <ICRS Coordinate: (ra, dec, distance) in (deg, deg, kpc)
182188 [(1.5, 3.5, 5.0), (2.5, 4.5, 5.0)]>
183189
184- An additional operation that may be useful is the ability to extract the
185- data in different representations. E.g., to get the Cartesian form of
186- an ICRS coordinate::
187-
188- >>> from astropy.coordinates import CartesianRepresentation
189- >>> cooi = ICRS(ra=0*u.deg, dec=45*u.deg, distance=10*u.pc)
190- >>> cooi.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP
191- <CartesianRepresentation (x, y, z) in pc
192- (7.07106781187, 0.0, 7.07106781187)>
190+ Similar broadcasting happens if you transform to another frame. E.g.::
191+
192+ >>> import numpy as np
193+ >>> from astropy.coordinates import EarthLocation, AltAz
194+ >>> coo = ICRS(ra=180.*u.deg, dec=51.477811*u.deg)
195+ >>> lf = AltAz(location=EarthLocation.of_site('greenwich'),
196+ ... obstime=['2012-03-21T00:00:00', '2012-06-21T00:00:00'])
197+ >>> coo.transform_to(lf) # doctest: +FLOAT_CMP
198+ <AltAz Coordinate (obstime=['2012-03-21T00:00:00.000' '2012-06-21T00:00:00.000'], location=(3980608.9024681724, -102.47522910648239, 4966861.273100675) m, pressure=0.0 hPa, temperature=0.0 deg_C, relative_humidity=0, obswl=1.0 micron): (az, alt) in deg
199+ [(94.71264994, 89.2142425), (307.69488826, 37.98077772)]>
200+
201+ Above, the shapes -- ``() `` for ``coo `` and ``(2,) `` for ``lf `` -- were
202+ broadcast against each other. If you wished to determine the positions for a
203+ set of coordinates, you'd need to make sure that the shapes allowed this::
204+
205+ >>> coo2 = ICRS(ra=[180., 225., 270.]*u.deg, dec=[51.5, 0., 51.5]*u.deg)
206+ >>> coo2.transform_to(lf)
207+ Traceback (most recent call last):
208+ ...
209+ ValueError: shape mismatch: objects cannot be broadcast to a single shape
210+ >>> coo2.shape
211+ (3,)
212+ >>> lf.shape
213+ (2,)
214+ >>> lf2 = lf[:, np.newaxis]
215+ >>> lf2.shape
216+ (2, 1)
217+ >>> coo2.transform_to(lf2) # doctest: +FLOAT_CMP
218+ <AltAz Coordinate (obstime=[['2012-03-21T00:00:00.000' '2012-03-21T00:00:00.000'
219+ '2012-03-21T00:00:00.000']
220+ ['2012-06-21T00:00:00.000' '2012-06-21T00:00:00.000'
221+ '2012-06-21T00:00:00.000']], location=(3980608.9024681724, -102.47522910648239, 4966861.273100675) m, pressure=0.0 hPa, temperature=0.0 deg_C, relative_humidity=0, obswl=1.0 micron): (az, alt) in deg
222+ [[(93.09845202, 89.21613119), (126.85789652, 25.46600543),
223+ (51.37993229, 37.18532521)],
224+ [(307.71713699, 37.99437658), (231.37407871, 26.36768329),
225+ (85.42187335, 89.69297997)]]>
226+
227+ .. Note ::
228+ One sees that frames without data have a ``shape `` that is determined by
229+ their frame attributes. For frames with data the ``shape `` always is that
230+ of the data; any non-scalar attributes are broadcast to have matching shape
231+ (as can be seen for ``obstime `` in the last line above).
193232
194233Transforming between Frames
195234===========================
0 commit comments