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')
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)
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 local_sidereal_time() routine also outputs the lst-index and lst-sequence at the given time.
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 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.
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
>>> from mascara.observer import Camera
>>> mycamera = Camera('mycamera', filename='mycaminfo.dat')
Since it can happen that the observer is unsure of the pointing of his camera, mascara.observer.Camera disposes of a function to find the precise pointing 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.
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 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.
mascara.observer.Camera supplies functions to transform a set of Horizontal coordinates (altitude and azimuth) into pixel coordinates.
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 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. 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 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. 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 mascara.observer.Camera.correct_positions() to the existing X and Y positions.
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 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 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)
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.
mascara.observer.coordinates is mostly called indirectly by functions in Site or Camera. However some functions may also be of interest.
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)
This class defines a location on Earth from which the sky is observable It is defined by latitude and longitude, and name of the observing site.
define an observing site:
>>> mysite = Site(latitude=53.43, longitude=-17.32, elevation=23, name='somewhere')
get the local sidereal time at that site:
>>> lst = mysite.local_sidereal_time(datetime.datetime.utcnow())
convert ra-dec coordinates into alt-az coordinates at a given date
>>> alt, az, visible_stars = mysite.apparent_stars(ra, dec, now)
and convert back alt, az into ra, dec
>>> ra, dec = mysite.projection_on_sky(alt, az, now)
for a given local sidereal time at the defined observation site.
Outputs:
alt, az vectors of same dimensions as the inputs.
Example:
We want to convert a set of equatorial coordinates in horizontal ones:
>>> import numpy as np >>> from mascara.observer import Site >>> ra = np.array([1.2391, 20.4982, 35.9821])
>>> dec = np.array([-30.4135, 35.0982, -31.0918])
>>> LE = Site(lat, lng)
>>> alt, az = LE.Equatorial2Horizontal(ra, dec, datetime.datetime.utcnow())
The function shouldn’t be used alone since it doesn’t make any correction for precession, nutation, aberration nor refraction.
Converts the horizontal coordinates which are site dependent to equatorial coordinates.
Inputs:
- alt, a scalar or vector of altitudes
- az, a scalar or vector of azimuth, of same size as alt.
- date, the date to perform the conversion. It can be a datetime object, or a float64(JD)
- refraction, if True computes the refraction corrected
- degree, (default = True) set if the input coordinates are in degree.
given time/date.
Inputs:
the chosen date. Supported formats are: datetime:object, JD:float64 or a list/tupler [yy,mth, day, hr,mn,sec]
Keywords:
apparent, set this to take into account the nutation of the Earth’s rotation.
Output: the altitude of the Sun.
Generate a site by specifying the latitude and longitude in degrees, and optionally a name for the observatory
>>> mysite = Site('MySAvedSite.dat')
>>> mysite = Site(34, -17.42, 23, name='mysite)
>>> mysite = Site(latitude=34.2, longitude=-17.42, elevation=23, name='mysite')
Append a site information line to the filename.
Calculate from a list of (ra, dec) coordinates which stars are visible from Site at the given time
Inputs :
ra, a scalar or a vector of right ascension coordinates
dec, a scalar or a vector of declinations
date, the time chose for the calculation. Can be datetime object or JD
Keywords:
precession= True, account for precession in the coordinate conversion
nutation=True, account for nutation in the coordinate conversion
aberration=True, account for annual aberrations
refraction=True, to computer the apparent altitude of the stars
Outputs:
alt, az the horizontal coordinates of the apparent stars
Attention!!! the dimension of alt, az may be smaller than the inputs dimensions. If the star is not visible, no output!
Compute the local siderial time at the given Site, based on a time input. Uses the Greenwich Mean/Apparent Sidereal Time for the calculations.
apparent, to calculate the apparent sidereal time (LAST) taking into account the nutation of the Earth
outformat, to define the form of the output. Default is in fractional hours (e.g 11.20374563....). Accepted are :
- ‘seconds’, the output is given in second
- ‘hhmmss’, the output is a 3-tuple (hr, mn, sec)
lstindex, if set, then the function returns TWO numbers, the LST at site, in the desired format, and the exposure index.
Outputs: the local Mean/Apparent Sidereal time in the given output format.
Example: To obtain the LAST in Leiden :
>>> from mascara.observer import Site>>> LE = Site(lat, lng, 0., name='Leiden') >>> lst = LE.local_sidereal_time(datetime.utcnow(), apparent=True)
Remarque: This does not take into account Time Zones when giving a datetime object in input!!! Refer to UTC instead!
The Camera class defines the orientation of the camera on sky. It is defined by the location of the center of the lens on the camera, Xo and Yo, the pointing on sky, Alto and Azo, and the rotation of the CCD, Tho.
Calculates the backward coefficients of the distortions for going from pixel coordinates to horizontal coordinates
Generates a camera by specifying the charateristics of the lens, and the pointing, orientation of the CCD. In addition a name is attributed to the camera.
- Inputs:
- if provided, the filename which contains the parameters of the camera.
- Keywords:
- altitude, the pointing altitude of the camera
- azimuth, the pointing azimuth of the camera
- orientation, the orientation of the camera on sky (if unsure, leave to zero)
- nx, the number of pixel in the X direction. Default is a 2k by 2k detector
- ny, the number of pixel in the Y direction.
- focal, the focal length of the lens. Default is 24mm
- pixsize, the pizel size of the CCD in micrometer. Default is 9um
- name, name of the camera
TO apply a small correction to the X and Y positions in addition to the global variations.
To apply small Y corrections to the predicted y position
xpre, ypre, the predicted positions of the stars on the CCD
- Keyword:
- solve, noCorrection, if True, no corrections are applied.
tnx function for calculating the lens distortions
tnx function for calculating the lens distortions
To evaluate how good is the astrometric solution. It uses the inputs coordinates (xpre, ypre) to search within a box of side radx2 any star above hmin x the standard deviation inside that box.
- Inputs:
- im, the reference image for the astrometry
- xpre, ypre, the stars positions in the CCD coordinates calculated via the astrometry
- Keywords:
- rad, the size of the box around those coordinates. If rad
is too small, the star may not be found. If rad is too big, outside stars may be found. Default is 15
- hmin, threshold for the find routine to detect a pick
above the background. Default is 4. By setting hmin smaller one may detect more stars, but the routine also becomes slower.
- Outputs:
- xc, yc, the coordinates of the stars found nearby of the
inputs coordinates. xc, yc may be of smaller dimension than xpre, ypre if the astrometry is very bad, or the star too diformed.
- matchit, an index array to adapt xpre,ypre to the dimension
- of xc, yc
- mdist, the median distance between the prediction stellar
position and the found stellar position. A rejection of outliers is applied before returning.
Find the pointing of the camera
im, the night image to use as reference for fonding the pointing
at the time the reference image was taken
vmag, the corresponding Vmagnitude of the visible stars.
Extract from file the parameters defining the camera. caminfo is an unique file containing:
To get back from CCD position to sky
astrocheck calculates the alt-az positions of 5 points on the CCD at the given time. The points are respectively, center of CCD, 1/4 left top corner, 1/4 right top corner, 1/4 bottom left corner and 1/4 bottom right corner.
The resulting alt and az are written to file.
into sky alt-az coordinates. The conversion tankes into accound the lens properties, via an N order polynomial to correct for most distortions.
Inputs:
x, y, two vectors of equal size representing the coordinates of the stars on the CCD
- Outputs:
- alt, az, two vectors of equal size giving the horizontal stellar
coordinates.
readAstroCheck reads in the astrocheck file and returns the entries in an array.
Reloads the camera using the infos from default file
solve_astrometry calculates the astrometric solution for the observing set-up. First it verifies the current pointing/lens solution by searching for an observed star in the neighborhood of a predicted position. If the find rate is very high (define very high with prerate), the pointing/lens parameters are correct, and the program exits immediately.
to calculate the positional corrections to apply to the X and Y positions
solve the equations to modelise the lens distortions using tnx approach.
The conversion take into account the characteristics of the camera lens, which defines the camera. In addition a N order polynomial is provided to correct the aberration of the objective.
Inputs:
alt, az, two vectors of equal size
Outputs:
x, y, two vectors of equl size giving the pixel coordinates of the stars.
inCCD, the indices of the stars inside the camera. To be used later in the reduction process for the ID and the Vmag...
Keywords:
margin, set this keyword to define a margin around the CCD. This is especially usefull when the pointing of the camera is not precise.
degree, to do the calculation in degree or if the inputs are in degrees global, set this keyword to the value defining by how much the predicted stellar position can be outside the CCD.
order, the order of the polynomial for fitting the lens
local, default is True. If set, only X and Y coordinates inside the CCD are returned. If False, then use inCCD to obtain the coordinates only in the CCD
- Example:
- To find the stellar position in the CCD:
>>> x, y, inCCD = Cam.visible_stars(alt, az, degree=True)
>>> x, y, glCCD = Cam.visible_stars(alt, az, degree=True, margin=500)
The coordinates module defines a set of function which are exclusively related to coordinates conversions and coordinates updates.
mascara.observer.coordinates contains the functions to compute nutation and precession parameters. Furthermore, it also contains the functions to compute many planetary elements (mean longitude, mean anomaly ...) for the Sun, the Earth, the Moon and some other planets.
Nutation calculates for a given date the mean obliquity, the nutation longitude and the nutation obliquity according to the IAU 2000B model. The Delaunay coefficients are from Simon and al. (1994). The model is simplified to the coefficients higher than 0.05”. Obliquity is calculated for J2000.
All outputs are in RADIAN
of the Earth’s nutation effects. The angles should have been calculated via Nutation before input. The matrix is calculated according to the IAU 2000 standard, using the formulas from the USNO circular n179.
Keywords: ?
Output : Nmatrix, the nutation rotation matrix.
Precession calculates the RA and Dec coordinates changes from a reference epoch to a new epoch.
Comments: the formulas used here respected the IAU 2000 resolution. They were extracted from the paper by Capitaine and al (2003), “Expressions for IAU 2000 precession quantities”
A Bias matrix is required to convert from ICRS data to the dynamical mean equation and equinox J2000.
Calculates the GMST at the current observation date. This is the first step towards the calculation of the Local Mean Sidereal Time (LMST). The coefficients are extracted from the circular 179 of USNO.
Defines the Mean longitude of the Moon referred to the mean equinox of the date
Gives the mean elongation of the Moon from the Sun, and the corresponding correction term at the given date t.
Forms the mean anomaly term for the Moon at the given Julian date t.
Comment: The formula is extracted from Simon and al (1994).
Computes the equation of centre of the Sun at the given date.
SunCorrLng computes the corrected Sun’s Mean Longitude. It takes into account the perturbation terms of Venus, Mars, Jupiter and the Moon, the mean ellipticity of the Earth, the long term variations and the abberations.
There remain some long term annual/semi-annual variations in the coordinates. These affect the ra and dec values at the most at the solstice. However the errors induced are less than one degree.
The code uses the latest formulas for the mean elements of the planets.