:py:mod:`aces.obsplan.tile` =========================== .. py:module:: aces.obsplan.tile .. autoapi-nested-parse:: Routines to support tiling the spherical sky. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: aces.obsplan.tile.Tile aces.obsplan.tile.SphericalPolygon aces.obsplan.tile.EllipsoidTool Functions ~~~~~~~~~ .. autoapisummary:: aces.obsplan.tile.prefix aces.obsplan.tile.ang_unwrap aces.obsplan.tile.vec_skp aces.obsplan.tile.xyz_rd aces.obsplan.tile.get_gc_pole aces.obsplan.tile.get_gc_intersect aces.obsplan.tile.refpos_to_euler aces.obsplan.tile.get_nlon_tiles aces.obsplan.tile.get_lon_span aces.obsplan.tile.get_tiling aces.obsplan.tile.tile_dec_band aces.obsplan.tile.tile_polar_cap aces.obsplan.tile.tile_pol_to_pol aces.obsplan.tile.rectangle_area aces.obsplan.tile.polygon_area aces.obsplan.tile.find_centroid_mass aces.obsplan.tile.find_centroid_kh aces.obsplan.tile.rotate_to_orig aces.obsplan.tile.make_box aces.obsplan.tile.get_lat_lims aces.obsplan.tile.get_centres aces.obsplan.tile.tile_polygon aces.obsplan.tile.mask_tiles aces.obsplan.tile.get_polygons aces.obsplan.tile.rotate_orig_to_pole aces.obsplan.tile.rotmat aces.obsplan.tile.rotate_x aces.obsplan.tile.rotate_z aces.obsplan.tile.transform Attributes ~~~~~~~~~~ .. autoapisummary:: aces.obsplan.tile.ster_to_sqdeg aces.obsplan.tile.twopi aces.obsplan.tile.overlay_format aces.obsplan.tile.overlay_label_format .. py:data:: ster_to_sqdeg .. py:data:: twopi .. py:data:: overlay_format .. py:data:: overlay_label_format .. py:function:: prefix(word, pfx) Add a prefix to a word, unless it is already present. :param word: The string to be prefixed :param pfx: The prefix :return: The prefixed word. .. py:class:: Tile(ident, lon, lat, posang) Bases: :py:obj:`object` The Tile object represents a single tile, uniquely defined within a set by location on the celestial sphere, and position angle. All tiles share parameters that are set in the initialise class method that must be called before any Tile object can be created. :param ident: Integer identifier :type ident: int :param lon: tile position in longitude (radians) :type lon: float :param lat: tile position in latitude (radians) :type lat: float :param posang: tile position angle (degrees) :type posang: float .. py:attribute:: n_pole .. py:attribute:: l0 .. py:attribute:: euler_zxz .. py:attribute:: origin .. py:attribute:: quadrant_select .. py:attribute:: trans_matrices .. py:attribute:: centre_matrix .. py:attribute:: label :value: '' .. py:attribute:: bf_pa :value: 0.0 .. py:attribute:: coord :value: 'J2000' .. py:attribute:: footprint .. py:attribute:: fp_factory .. py:attribute:: MRO_latitude .. py:attribute:: za_limit .. py:attribute:: northern_limit .. py:method:: initialise(origin, label, footprint, bf_pa, coord='J2000') :classmethod: Initialise the class variables for all subsequent creations of Tile objects. :param origin: Centre of tile sphere in given coordinates as Skypos :type origin: Skypos :param label: Label for tiling; used in names of all related product files :type label: string :param footprint: Footprint object used for this tiling :type footprint: Footprint :param bf_pa: beam-forming position angle (degrees) :type bf_pa: float :param coord: Name of coordinates of tiling ('J2000', 'GALAC', 'MAGEL') :type coord string .. py:method:: __str__() :return: A formatted string giving tile id, celestial position and position angle .. py:method:: check_accessible() This function is trivial: it checks for tile positions beyond ASKAP's northern limit. But could be extended to incorporate additional position constraints. :return: Whether a tile at this position is accessible by ASKAP. .. py:method:: get_overlay(kind='ds9') Returns a string suitable for overlaying the tile outline on sky maps. Supported kinds are ds9 (works with aladin) and kvis. The string can be written to a file to be presented to image display program. :param kind: "ds9" or "kvis" :return: A formatted string describing the tile outline in the requested format. .. py:method:: get_overlay_label(label, kind='ds9') Returns a string suitable for overlaying the given label on sky maps and the current tile position. Supported kinds are ds9 (works with aladin) and kvis. The string can be written to a file to be presented to image display program. :param label: The label :param kind: "ds9" or "kvis" :return: A formatted string giving label and its position in correct format .. py:method:: get_footprint_cmd(kind='ds9') Returns a command line string that will execute the footprint-plan.py script that produces plots and overlays of the beam positions within a footprint. For example: footprint-plan.py -n ak:square_6x6 -p 0.9 -r 141.382178,-37.100000 -o 141-37 -f kvis -w 0.9 :return: The command line string. .. py:method:: get_parset_entry(with_interleave=True) Returns the parset entries for observing this tile, and optionally, the interleaved positions. The entry keys are * common.target.src%d.field_direction * common.target.src%d.field_name * common.target.src%d.pol_axis The "%d" formatting code is replaced by the tile identifier number elsewhere. :param with_interleave: :return: A list of strings, each of the form = .. py:method:: get_corners() Returns the sky coordinates in the J2000 celestial coordinate frame of each corner for this tile. :return: ndarray of Skypos objects holding the four corner coordinates. .. py:method:: get_poly() Returns the sky coordinates in the J2000 celestial coordinate frame of each corner for this tile. :return: list of Skypos objects holding the four corner coordinates. .. py:method:: get_poly_native() Returns the sky coordinates in the user-specified tiling coordinate frame of each corner for this tile. :return: list of Skypos objects holding the four corner coordinates. .. py:method:: get_interleaved_tile(quadrant=0) Returns a tile that is offset from the current tile by half the tile spacing in both cardinal directions. The sign of each offset is determined by the value of quadrant. This form of interleaving differs from the standard "beam interleaving" in which the interleaved position is offset from the original by a fraction of a beam spacing so as to place the new beam positions in the sensitivity minima of the original tile position. The offset returned by this procedure is intended to smooth sensitivity variations that are dependent on axial distance, independent of beam position. For all-sky tilings, it is of limited use as the set of interleaved tiles do not as neatly tile the sky. :param quadrant: :return: A new Tile object offset froom the current tile. .. py:method:: _set_posang_deg() Return the required antenna position angle, which differs from the tile position angle by the position angle used at beam forming. :return: Antenna position angle (degrees). .. py:method:: _make_name() Construct a string name of form hhmm+/-dd :return: tile name .. py:method:: _get_corners() Calculate and return the sky coodinates of the tile corners. :return: a list containing a Skypos object for each corner. .. py:method:: _get_ra_mid_wid() Needed to help with tiles that straddle 0 hours :return: .. py:function:: ang_unwrap(x, semi) Find the angle equivalent to x in the range [-semi, semi] where semi is the half-turn angle in the same units as x. Mostly, semi will be either 180 or pi. :param x: Given angle :param semi: Half-turn angle in same angular units as x :return: Angle equivalent to x in range [-semi, semi] .. py:function:: vec_skp(vec) Return a Skypos object given the direction as a 3-vector :param vec: The given direction :return: Direction as Skypos object .. py:function:: xyz_rd(v) Convert a 3-vector direction to (longitude, latitude) pair. :param v: Given direction as 3-vector :return: (longitude, latitude) pair (radians) .. py:function:: get_gc_pole(p1, p2) Find the pole of the great circle that passes through p1, p2. :param p1: Skypos object :param p2: Skypos object :return: A Skypos object giving the direction of one of the poles of the great circle passing though the two input positions. .. py:function:: get_gc_intersect(s1, s2) Given two great circles, specified by their poles, find the two intersection points. :param s1: Pole of first great circle as Skypos object :param s2: Pole of second great circle as Skypos object :return: A list of the two Skypos objects representing the two intersection points. .. py:function:: refpos_to_euler(lon, lat) .. py:function:: get_nlon_tiles(tile_pitch, beam_pitch, lon_span, lat) .. py:function:: get_lon_span(lat, cap_radius, tile_pitch) .. py:function:: get_tiling(tile_pitch, beam_pitch, lat_range, cap_radius, expansion='symmetric', mode='squeeze') .. py:function:: tile_dec_band(tile_pitches, beam_pitch, lat_range) .. py:function:: tile_polar_cap(tile_pitches, beam_pitch, dec_lim) .. py:function:: tile_pol_to_pol(tile_pitches, beam_pitch, dec_range, do_north=False) .. py:function:: rectangle_area(tile_pitches) .. py:function:: polygon_area(poly) Returns the area of a spherical polygon in steradians :param (ndarray) Array of polygon vertices of type Skypos .. py:function:: find_centroid_mass(poly) .. py:function:: find_centroid_kh(poly) .. py:function:: rotate_to_orig(poly, centroid, rot=0.0, forward=True) .. py:function:: make_box(poly) .. py:function:: get_lat_lims(box) .. py:function:: get_centres(pitch, extent) .. py:function:: tile_polygon(tile_pitches, polygon, force_symmetry=False) Computes sky positions and position angles for all positions in a quasi-rectangular grid and any interleaving points for each grid position. centre Skypos (ra,dec) of grid centre angle position angle of rectangle (radians) dela "horizontal" grid spacing (radians) deld "vertical" grid spacing (radians) nx,ny number of points horizontally, vertically iofs is a list of pairs, each pair an intereaving offset in polar (d,pa) (radians) long_shift Shifts the area along the "horizontal" great circle (radians) .. py:function:: mask_tiles(tilpos, tile_pitches, polygons) Take a set of tile positions and sizes and return a mask array of the same size with values set False for all tiles within any of the given polygons. The test for position relative to the polygons is based on the method of Bevis and Chatelain, with added steps to allow for polygon sides traversing a tile but with neither the tile centre or its corners falling within the polygon. :param tilpos: ndarray of shape [num_tiles, 3] giving tile locations and position angles (radians) :param tile_pitches: length rectangular tile sides (radians) :param polygons: list of polygons, each an ndarray of vertices as Skypos objects. :return: ndarray of booleans shape [num_tiles] .. py:class:: SphericalPolygon(polygon, external) Bases: :py:obj:`object` This class performs operations on polygons defined on the unit sphere. It includes an implementation of the Bevis and Chatelain method for determining whether a point on the unit sphere lies inside a polygon on that surface. The concept of "inside" is solidified by defining the input point (xlon,xlat) to be "outside" the polygon. Find a reference to the method at https://www.researchgate.net/publication/227017249_Locating_a_point_on_a_spherical_surface_relative_to_a_spherical_polygon Other methods exist, some claiming to be much more computationally efficient. For the application here, polygons with relatively few vertices are envisaged (10s or 100s), so computation time is not a serious concern. Other potential sources for this function are astropy.regions (seems immature at this time (2021November) and pyregion, which claims to parse ds9 region files and do some region computation, but does not suit this application. This method has the advantage of resorting to the fundamental geometric mathematics and will not suffer from updates in any external package. .. py:method:: get_location(plat, plon) .. py:method:: east_or_west(clon, dlon) :staticmethod: .. py:method:: transform_lon(plat, plon, qlat, qlon) :staticmethod: .. py:class:: EllipsoidTool Some stuff for playing with ellipsoids .. py:method:: get_min_vol_ellipse(P=None, tolerance=0.01) Find the minimum volume ellipsoid which holds all the points Based on work by Nima Moshtagh http://www.mathworks.com/matlabcentral/fileexchange/9542 and also by looking at: http://cctbx.sourceforge.net/current/python/scitbx.math.minimum_covering_ellipsoid.html Which is based on the first reference anyway! Here, P is a numpy array of N dimensional points like this: .. code-block:: P = [[x,y,z,...], <-- one point per line [x,y,z,...], [x,y,z,...]] Returns: (center, radii, rotation) .. py:method:: get_ellipsoid_volume(radii) :staticmethod: Calculate the volume of the blob .. py:function:: get_polygons(poly_file) .. py:function:: rotate_orig_to_pole(pole) .. py:function:: rotmat(angs) .. py:function:: rotate_x(a) .. py:function:: rotate_z(a) .. py:function:: transform(p, mat)