.. _sites: ******** Observer ******** The Site class ============== Initialisation -------------- Site defines an observing site giving its latitude and elongation coordinates. It can either be prompted directly >>> from mascara.observer import Site >>> mysite = Site(latitude=-17.23, longitude=51.234, elevation=0., name='mysite') Or read from an existing siteinfo.dat file: >>> mysite = Site(filename='mysite') Some parameters of the site can be updated or changed at any moment. >>> mysite._setPressure(955, unit = 'bar') >>> mysite._setTemperature(26.42, unit='celsius') Converting equatorial to horizontal coordinates ----------------------------------------------- Having a site defined, it is now possible to convert stellar Ra-Dec coordinates into local altitude-azimuth coordinate for a given observing time. The function ApparentStars takes per default into account the nutation, and precession of the Earth, the aberrations caused by the Sun and the refraction effects due to the atmosphere. >>> alt, az, visible = mysite.apparent_stars(ra, dec, date) Convenience functions --------------------- Moreover, we can check the altitude of the Sun or the Local Siderial Time at the observation site by giving in the UTC time: >>> sunalt, sunaz = mysite.Sunaltitude(datetime.datetime.utcnow()) >>> lst = mysite.local_sidereal_time(datetime.utcnow()) In addition, the :py:func:`local_sidereal_time` routine also outputs the lst-index and lst-sequence at the given time. Saving the site --------------- Finally, any changes in the observing site can be easily updated to the siteinfo file: >>> mysite._updateSiteInfo() Create a new file or add a new entry to the existing file: >>> mysite._writeSiteInfo(filename='mysiteinfo.dat', ID = 'MS') >>> mysite._appendSiteInfo(filename='mysiteinfo.dat') The Camera class ================ Introduction ------------ The Camera class allows the user to define an observing camera. It is in particular suited for detector - lens systems. The camera informations include basic details on the lens (focal length) and detector (pixel size, number of pixels). Furthermore a basic astrometric solution is calculated provided the user gives in a general pointing direction. The main advantage in using the Camera class lies in the alt-az to pixel position conversion. As such it allows the user to predict accurately the position of any object on the CCD when giving in a set of horizontal coordinates. Usage ----- The Camera instance is defined by providing the basic pointing orientation of the camera: - altitude - azimuth - orientation of the camera on sky. - central pixel in X direction - central pixel in Y direction Additional information can also be provided under the form of keywords: - focal = focal length of the lens - pixel size - total number of X pixels - total number of Y pixels Since one may use the same systems again and again, those informations can also be loaded from file. Define a Camera by knowing the pointing: >>> from mascara.observer import Camera >>> mycamera = Camera(altitude=45., azimuth=120., orientation=0. focal=20, pixsize=7.4, nx=2048, ny=4096) Pointing altitude is 67degree above horizon Pointing azimuth is 0.0degree from North Camera orientation is 0.0degree from North Focal length is 20mm Pixel size is 7.4 um Define a Camera from file: >>> from mascara.observer import Camera >>> mycamera = Camera('mycamera', filename='mycaminfo.dat') Finding the pointing of the camera ---------------------------------- Since it can happen that the observer is unsure of the pointing of his camera, :class:`mascara.observer.Camera` disposes of a function to find the precise pointing :meth:`sites.CamCoord.find_pointing`. The function however requires that the focal length of the camera lens and the pixel size are known. The process of finding the correct pointing is done iteratively: - a rough pointing is set, - the stars positions are computed for that pointing - and compared to observed stellar positions using Delaunay triangulation - if at least 5 Delaunay vortices could be matched together in size and magnitude, then the program solves for the pointing - else it tries another pointing. In order to optimize one chances to obtain a good pointing, it is adviced to : - use a good sky image, without clouds or Moon in the field - give as an input a first guess of the pointing. In that case the function will converge faster. Let's illustrate the use of this function. We assume we have a good sky image called image, and two arrays for the horizontal coordinates of our stellar catalog computed using the :meth:`sites.Site.ApparentStars` function. >>> from mascara.observer import Site, Camera >>> from mascara.funcs.utils import loadStellarCatalog >>> ra, dec, mag, bmag, sID, sptype = loadStellarCatalog(filename='YourFile.fits', Vmag=[4, 7.5]) >>> mysite = Site(28.76, -17.897, 10) >>> alt, az, vis = mysite.apparent_stars(ra, dec, jd) >>> vmag = mag[vis] >>> mycamera = Camera(altitude=35, azimuth=200, orientation=0, focal=24, pixsize=9.) >>> alt.shape, az.shape, vmag.shape (2102, ) (2102, ) (2102, ) >>> image.shape (2672, 4008) >>> mycamera.find_pointing(image, alt, az, vmag) Iterations 1, altitude 50.0, azimuth 8.8702898212 Found 4 potential good candidates Iterations 2, altitude 50.0, azimuth 17.7405796424 Found 2 potential good candidates ... Iterations 30, altitude 50.0, azimuth 266.108694636 Found 12 potential good candidates Found 184 potential good candidates Stability of the pointing after 12 iterations 0.0434935993137 If the function cannot find a stable pointing, the output would then be: >>> mycamera.find_pointing(image, alt, az, vmag, dtol=3., mtol=0.12) Stability of the pointing after 15 iterations 5.06009104279 The current pointing is not stable. Probably not a good one Give in another set of estimated altitude/azimuth Once the poingint of the camera is known, it is then possible to compute an astrometric solution for the camera, which will allow us to predict at any given time the position of the stars on the CCD. Calculating the astrometric solution ------------------------------------ :class:`mascara.observer.Camera` supplies functions to transform a set of Horizontal coordinates (altitude and azimuth) into pixel coordinates. .. _astrometrysketch: .. figure:: astrometry_sketch.png :alt: conversion from alt-az to x-y in steps :scale: 75% :align: center Transformation functions for switching back and forth between the different coordinates system used. In order to convert horizontal coordinates to pixels positions it is necessary to define the Pointing of the camera. If a first guess is available of the altitude and azimuth direction, it should be provided when loading the Camera instance. Else the pointing can be determine and refined using the function :meth:`mascara.observer.Camera.find_pointing` described earlier. With only the Pointing known, the conversion uses a first order linear relation to convert the horizontal to the CCD coordinates. However, for pixel or subpixel precise positions, this first order relation is not enough. :func:`mascara.observer.Camera.solve_astrometry` calculates on the basis of one good image (no Moon is possible, no clouds) the accurate Pointing of the camera and the distortions of the lens by comparing the predicted stellar positions to the positions found on the CCD. The astrometry is calculated using the TNX World Coordinate System (more information `here `_). The distortions are evaluated in each direction by a N-th order non linear polynomial and compared to the observed positions. For observations spanning a long time period, it could happens that the astrometric solution varies with time. While it is still possible to re-run :meth:`mascara.observer.camera.solve_astrometry` at regular interval, it is however then advised to calculate what small displacements are required to match sub-pixel accuracy on the basis of the existing astrometric solution. :meth:`mascara.observer.solve_corrections` will calculate for each X and Y direction the displacement to apply to each star based on the star position on the chip. These corrections are calculated per default on the first order. To apply these corrections, use :meth:`mascara.observer.Camera.correct_positions` to the existing X and Y positions. Convenience functions --------------------- Using the Camera instance presents many advantages via the use of the convenience functions implemented to translate horizontal coordinates into pixel coordinates and inversely. The function :meth:`mascara.observer.Camera.visible_stars` directly transforms a set of alt-az coordinates into the corresponding visible x-y positions, including the distortions caused by the optical lens. Inversely to convert a set of known x-y positions into their alt-az counterpart use :meth:`mascara.observer.Camera.projection_on_sky`. For instance, let us load a stellar catalogue, and find the positions of those stars on the CCD at a given time: >>> from mascara.observer import Camera, Site >>> from mascara.funcs.utils import loadStellarCatalog >>> mysite = Site(latitude=52.34, longitude= 4.89, elevation=0., name='Leiden') >>> mycamera = Camera(45, 120, 0., focal=24, pixsize=9, name='MyCamera') >>> ra, dec, mag, bmag, sId, Sptype = loadStellarCatalog(filename='StarCat.fits', Vmag=[2., 7.1]) >>> alt, az, visible = mysite.apparent_stars(ra, dec, datetime.datetime.(2015,2,2,23,12,34)) >>> x, y, inCCD = mycamera.visible_stars(alt, az) >>> xp, yp = mycamera.correct_positions(x, y) :meth:`mascara.observer.Camera.evaluate_astrometry` evaluates the accuracy of an astrometric solution based on one image and a set of stellar positions on the CCD. A typical median distance of 0.2 pixels between observed and predicted star positions characterises a good astrometric solution. This value tends to increase the more stars are evaluated. The coordinates modules ======================= :mod:`mascara.observer.coordinates` is mostly called indirectly by functions in Site or Camera. However some functions may also be of interest. Nutation and Precession ----------------------- During the conversion of the equatorial to horizontal coordinates, the equatorial coordinates are corrected for the Earth nutation and precession. As reference the equatorial coordinates used by mascara are in FK5 system, at the J2000 epoch. This defines a referential frame which was defined as true for 01.01.2000, but may no longer be accurate at our current observation date. In order to correct for this, we transform our FK5 coordinates into the Celestial Intermediate Reference System (CIRS) which shall then be used to compute the alt and az coordinates of our stars. During the transformation, we apply several rotations matrices to our original coordinate system: - a bias matrix to go from FK5 to th ICRS (International Coordinate Referential system) - a precession matrix, - and a nutation matrix These rotation matrices are defined after the IAU2000B model using the parameters found in the papers of Capitaine and al (2003), and Wallace and al (2004). Then the transformations are simply matrix multiplications: >>> Y = N*P*B*X Where Y and X are our coordinates in a rectangular referential To call those matrices: >>> import mascara.observer.coordinates as coordinates >>> P = coordinates.precession_matrix(jd) >>> N = coordinates.nutation_matrix(jd) >>> B = coordinates.bias_matrix() Moreover, if only the obliquity of the Earth ecliptic is required: >>> obl, dpsi, deps = coordinates.nutation(jd) Planetary mean elements ----------------------- :mod:`mascara.observer.coordinates` also include several planetara mean elements which are calculated after the formulates of Simon and al (1994): - mean longitude of the Earth - mean anomaly of the Sun - mean anomaly of the Moon - longitude of the ascending node of the Moon - mean elongation of the Moon - ... And also some quick functions to compute the True mean elements: - :func:`mascara.observer.coordinates.EquationCenter` - :func:`mascara.observer.coordinates.ComputeExcentricity References/APIs =============== .. automodule:: mascara.observer The Site class -------------- .. autoclass:: mascara.observer.Site :members: __init__, _setTemperature, _setPressure, apparent_stars, Sunaltitude, local_sidereal_time, _getsiteinfo, _writeSiteInfo, _updateSiteInfo, _appendSiteInfo, Equatorial2Horizontal, Horizontal2Equatorial The Camera class ---------------- .. autoclass:: mascara.observer.Camera :members: __init__, visible_stars, solve_astrometry, solve_corrections, solve_distortions, correct_positions, projection_on_sky, evaluate_astrometry, logAstrometryCheck, readAstroCheck, reload, getcaminfo, writecamerafile, distortX_tnx, distortY_tnx, correctX, correctY, invert_correction, ReverseTnx, find_pointing The Coordinates module ---------------------- .. automodule:: mascara.observer.coordinates :members: Nutation, nutation_matrix, precession_matrix, bias_matrix, Aberrations, greenwich_mean_sidereal_time, earth_rotation, MoonMeanLong, MoonMeanElong, MoonMeanAnomaly, ComputeExcentricity, EquationCenter, SunCoord, SunMeanAnomaly, EarthExcentricity