Gyoto
Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Private Attributes | Friends | List of all members
Gyoto::Screen Class Reference

The camera with which the Astrobj is observed. More...

#include <GyotoScreen.h>

Inheritance diagram for Gyoto::Screen:
Gyoto::SmartPointee

Public Member Functions

 Screen ()
 Default constructor.
 
 Screen (const Screen &)
 Copy constructor.
 
Screenclone () const
 Cloner.
 
virtual ~Screen ()
 Destructor.
 
void setProjection (const double paln, const double inclination, const double argument)
 Set inclination etc.
 
void setProjection (const double distance, const double paln, const double inclination, const double argument)
 Set distance, inclination etc.
 
void distance (double dist)
 Set distance from observer. More...
 
void dMax (double dist)
 Set ray-tracing maximum distance. More...
 
void distance (double dist, const std::string unit)
 Set distance from observer. More...
 
void inclination (double)
 Set inclination relative to line-of-sight. More...
 
void inclination (double, const std::string &unit)
 Set inclination relative to line-of-sight. More...
 
void PALN (double)
 Set position angle of the line of nodes.
 
void PALN (double, const std::string &unit)
 Set position angle of the line of nodes.
 
void argument (double)
 Set angle beetwen line of nodes and X axis of object.
 
void argument (double, const std::string &unit)
 Set angle beetwen line of nodes and X axis of object.
 
void spectrometer (SmartPointer< Spectrometer::Generic > spectro)
 Set Screen::spectro_.
 
SmartPointer
< Spectrometer::Generic
spectrometer () const
 Get Screen::spectro_.
 
void freqObs (double fo)
 Set freq_obs_. More...
 
void freqObs (double fo, const std::string &unit)
 Set freq_obs_. More...
 
double freqObs () const
 Get freq_obs_.
 
double freqObs (const std::string &unit) const
 Get freq_obs_. More...
 
void setObserverPos (const double pos[4])
 Alternative way to set projection. More...
 
void setFourVel (const double coord[4])
 Sets the observer's 4-velocity.
 
void setScreen1 (const double coord[4])
 Sets the screen vector e1.
 
void setScreen2 (const double coord[4])
 Sets the screen vector e2.
 
void setScreen3 (const double coord[4])
 Sets the screen vector e3 (normal)
 
int coordKind () const
 Get coordinate kind. More...
 
double distance () const
 Get distance from observer. More...
 
double distance (const std::string &) const
 Get distance from observer. More...
 
double dMax () const
 Get maximum ray-tracing distance. More...
 
double inclination () const
 Get inclination relative to line-of-sight. More...
 
double inclination (const std::string &) const
 Get inclination relative to line-of-sight. More...
 
double PALN () const
 Get position angle of the line of nodes.
 
double PALN (const std::string &) const
 Get position angle of the line of nodes.
 
double argument () const
 Get angle between line of nodes and X axis of object.
 
double argument (const std::string &) const
 Get angle between line of nodes and X axis of object.
 
SmartPointer< Metric::Genericmetric () const
 Get Screen::gg_.
 
void metric (SmartPointer< Metric::Generic > gg)
 Set Screen::gg_.
 
double time ()
 Get observing date in seconds.
 
double time (const std::string &)
 Get observing date in seconds.
 
void time (double, const std::string &)
 Set observing date in specified unit.
 
void time (double)
 Set observing date in seconds.
 
double fieldOfView ()
 Get Screen::fov_ in radians.
 
double fieldOfView (std::string unit)
 Get Screen::fov_ in specified unit.
 
void fieldOfView (double)
 Set Screen::fov_ in radians.
 
void fieldOfView (double, const std::string &unit)
 Set Screen::fov_ in specified unit.
 
void alpha0 (double)
 Set direction of the center of the field.
 
void alpha0 (double, const std::string &unit)
 Set direction of the center of the field in specified unit.
 
double alpha0 () const
 Get direction of the center of the field.
 
double alpha0 (std::string unit)
 Get direction of the center of the field in specified unit.
 
void delta0 (double)
 Set direction of the center of the field.
 
void delta0 (double, const std::string &unit)
 Set direction of the center of the field in specified unit.
 
double delta0 () const
 Get direction of the center of the field.
 
double delta0 (std::string unit)
 Get direction of the center of the field in specified unit.
 
void setAnglekind (int)
 Set Screen::anglekind_.
 
size_t resolution ()
 Get Screen::npix_.
 
void resolution (size_t)
 Set Screen::npix_.
 
void mask (double const *const mm, size_t resolution=0)
 Set mask_ from array. More...
 
double const * mask () const
 Retrieve const pointer to mask_.
 
void fitsReadMask (std::string fname)
 Read mask_ from FITS file.
 
void fitsWriteMask (std::string fname)
 Save mask_ from FITS file.
 
bool operator() (size_t, size_t)
 Whether this pixel should be ray-traced. More...
 
void getObserverPos (double coord[]) const
 4-Position of the observer relative to the metric More...
 
void getFourVel (double fourvel[]) const
 Get copy of Screen::fourvel_. More...
 
void getScreen1 (double output[]) const
 Get copy of Screen::screen1_. More...
 
void getScreen2 (double output[]) const
 Get copy of Screen::screen2_. More...
 
void getScreen3 (double output[]) const
 Get copy of Screen::screen3_. More...
 
void getRayCoord (double x, double y, double coord[]) const
 Get 8-coordinate of Photon hitting screen from a given direction. More...
 
void getRayCoord (const size_t i, const size_t j, double coord[]) const
 Get 8-coordinate of Photon hitting screen pixel. More...
 
void coordToSky (const double pos[4], double skypos[3]) const
 Convert 4-position to 3-sky position.
 
void coordToXYZ (const double pos[4], double xyz[3]) const
 Convert 4-position to 3-cartesian coordinates.
 
void computeBaseVectors ()
 Compute base vectors according to projection parameters.
 
std::ostream & print (std::ostream &) const
 Display. More...
 
std::ostream & printBaseVectors (std::ostream &) const
 Debug helper.
 
void mapPixUnit ()
 Map "pix" and "pixel" to angular pixel width in unit system. More...
 
void unmapPixUnit ()
 Unmap "pix" and "pixel" from unit system. More...
 
void fillElement (FactoryMessenger *fmp)
 

Static Public Member Functions

static SmartPointer< ScreenSubcontractor (FactoryMessenger *fmp)
 Instanciate a Screen from XML entity.
 

Protected Types

typedef Gyoto::SmartPointer
< Gyoto::SmartPointee
Subcontractor_t (Gyoto::FactoryMessenger *)
 A subcontractor builds an object upon order from the Factory. More...
 

Protected Member Functions

void incRefCount ()
 Increment the reference counter. Warning: Don't mess with the counter.
 
int decRefCount ()
 Decrement the reference counter and return current value. Warning: Don't mess with the counter.
 
int getRefCount ()
 Get the current number of references.
 

Private Attributes

double tobs_
 Observing date in s.
 
double fov_
 Field-of-view in rad.
 
size_t npix_
 Resolution in pixels.
 
double * mask_
 Mask with 0 where the ray-tracing should not be performed.
 
std::string mask_filename_
 Last read or written FITS file. More...
 
double distance_
 Distance to the observer in m.
 
double dmax_
 Maximum distance from which the photons are launched (geometrical units)
 
int anglekind_
 Screen angles kind (0: equatorial, 1: spherical)
 
double euler_ [3]
 Euler angles. More...
 
double ex_ [3]
 Sky coordinate of base X vector.
 
double ey_ [3]
 Sky coordinate of base Y vector.
 
double ez_ [3]
 Sky coordinate of base Z vector.
 
double fourvel_ [4]
 Observer's 4-velocity.
 
double screen1_ [4]
 Screen e1 vector.
 
double screen2_ [4]
 Screen e2 vector.
 
double screen3_ [4]
 Screen e3 vector (normal)
 
double alpha0_
 Screen orientation (0,0) is right towards the BH.
 
double delta0_
 Screen orientation (0,0) is right towards the BH.
 
SmartPointer< Metric::Genericgg_
 The Metric in this end of the Universe.
 
SmartPointer
< Spectrometer::Generic
spectro_
 Gyoto::Spectrometer::Generic subclass instance used for quantities Spectrum and BinSpectrum.
 
double freq_obs_
 Frequency at which the observer observes. More...
 

Friends

class Gyoto::SmartPointer< Gyoto::Screen >
 

Detailed Description

The camera with which the Astrobj is observed.

In the observer-centric point-of-view, the center of the Metric's coordinate system is positioned relatively to the observing Screen using three Euler angles and the distance (in meters). The three Euler angles are:

In addition, the Screen conveys:

The scalar FreqObs defines the observing frequency for Scenery quantity Intensity.

Likewise, a Gyoto::Spectrometer defines for which frequencies spectra are computed (when the Quantity Spectrum is requested in the Scenery).

For the sake of theoreticians, there is an alternate way of specifying the relative position of the Screen and Metric, by specifying the 4-coordinates of the Screen in the Metric's coordinate system (in that case, eerything is specified in geometrical units).

So an XML stanza for a Screen may look like that:

<Time> 1000. </Time>
<FieldOfView> 0.3141592653589793 </FieldOfView>
<Resolution> 128 </Resolution>
<Distance> 1e30 </Distance>
<PALN> 3.14159 </PALN>
<Inclination> 2.0944 </Inclination>
<Argument> -2.0944 </Argument>
<Spectrometer kind="freqlog" nsamples="10"> 17. 23. </Spectrometer>
<FreqObs> 1e20 </FreqObs>

or like that:

<Position> 1000. 1000. 0.15. 0.</Position>
<FieldOfView> 0.3141592653589793 </FieldOfView>
<Resolution> 128 </Resolution>
<Spectrometer kind="freqlog" nsamples="10"> 17. 23. </Spectrometer>
<FreqObs> 1e20 </FreqObs>

Units can be specified using the unit attribute in the XML file, for instance:

<Distance unit="kpc"> 8 </Distance>

Possible units are (with [] noting the default):

When the distance is really large and most of the ray-tracing would happen de facto in flat space, the camera is transported to a location at a reasonable distance from the metric and the images are scaled accordingly. The default value for this distance should be fine, but it can be customized using the "dmax" attribute of the "Distance" element. "dmax" is always expressed in geometrical units:

<Distance unit="kpc" dmax="1e7"> 8 </Distance>

Symptoms when dmax is too large include pixelization of the image (neighbouring photons are numerically identical) and other numerical overflows. dmax is too small when it is apparent that changing it yields projection effects. dmax must be large compared to rmax in the Astrobj and ideally, changing it by an order of magnitude should not yield significant changes in the ray-traced image.

A mask may be used to limit ray-tracing to only some portions of the field. The Scenery checks whether a mask is to be used using Screen::operator()(size_t i, size_t j). The mask can be loaded from a FITS file as a square image of doubles:

<Mask>maskfile.fits</Mask>

The mask needs to be have the same size as the Screen itself, so loading a mask also sets the resolution, and changing the resolution after setting a mask also removes the mask.

Member Typedef Documentation

typedef Gyoto::SmartPointer<Gyoto::SmartPointee> Gyoto::SmartPointee::Subcontractor_t(Gyoto::FactoryMessenger *)
inherited

A subcontractor builds an object upon order from the Factory.

Various classes need to provide a subcontractor to be able to instanciate themselves upon order from the Factory. A subcontractor is a function (often a static member function) which accepts a pointer to a FactoryMessenger as unique parameter, communicates with the Factory using this messenger to read an XML description of the object to build, and returns this objet. SmartPointee::Subcontractor_t* is just generic enough a typedef to cast to and from other subcontractor types: Astrobj::Subcontractor_t, Metric::Subcontractor_t, Spectrum::Subcontractor_t. A subcontractor needs to be registered using the relevant Register() function: Astrobj::Register(), Metric::Register(), Spectrum::Register().

Member Function Documentation

int Gyoto::Screen::coordKind ( ) const

Get coordinate kind.

From Screen::gg_.

void Gyoto::Screen::distance ( double  dist)

Set distance from observer.

Parameters
distDistance in meters.
void Gyoto::Screen::distance ( double  dist,
const std::string  unit 
)

Set distance from observer.

Parameters
distthe distance expressed in the specified unit;
unitconvertible to meters
double Gyoto::Screen::distance ( ) const

Get distance from observer.

In meters.

double Gyoto::Screen::distance ( const std::string &  ) const

Get distance from observer.

In specified unit.Get distance from observer

void Gyoto::Screen::dMax ( double  dist)

Set ray-tracing maximum distance.

Parameters
distDistance in geometrical units.
double Gyoto::Screen::dMax ( ) const

Get maximum ray-tracing distance.

In geometrical units.

void Gyoto::Screen::fillElement ( FactoryMessenger *  fmp)

called from Factory

void Gyoto::Screen::freqObs ( double  fo)

Set freq_obs_.

Parameters
fodouble: observing frequency in Hz
void Gyoto::Screen::freqObs ( double  fo,
const std::string &  unit 
)

Set freq_obs_.

Parameters
fodouble: observing frequency (or wavelength) in "unit"
unitstring: unit in which fo is expressed, convertable to Herz or meters or energy.
double Gyoto::Screen::freqObs ( const std::string &  unit) const

Get freq_obs_.

Parameters
unitstring: unit in which freq_obs_ should be returned is expressed, convertable to Herz or meters or energy.
void Gyoto::Screen::getFourVel ( double  fourvel[]) const

Get copy of Screen::fourvel_.

Parameters
[out]fourvelpreallocated 4-element array
void Gyoto::Screen::getObserverPos ( double  coord[]) const

4-Position of the observer relative to the metric

A Screen is positioned relative to the observer with four elements: Screen::distance, Screen::inclination, Screen::paln and Screen::argument.

This function returns the position of the observer relative to the metric system in Screen::gg_, using these parameters. The output parameter is coord.

Parameters
[out]coordposition of the observer. Must be preallocated.
void Gyoto::Screen::getRayCoord ( double  x,
double  y,
double  coord[] 
) const

Get 8-coordinate of Photon hitting screen from a given direction.

Similar to Screen::getObserverPos() but will return in addition the 4-velocity of a photon corresponding to the sky direction given by x and y.

Parameters
[in]xRA (d_alpha*cos(delta)) offset in radians;
[in]yDec offset (d_delta) in radians;
[out]coordposition-velocity of the observer Photon. Preallocated.
void Gyoto::Screen::getRayCoord ( const size_t  i,
const size_t  j,
double  coord[] 
) const

Get 8-coordinate of Photon hitting screen pixel.

Similar to Screen::getObserverPos() but will return in addition the 4-velocity of a photon corresponding to the sky direction given by x and y.

Parameters
[in]i,jpixel coordinates
[out]coordposition-velocity of the Photon. Preallocated.
void Gyoto::Screen::getScreen1 ( double  output[]) const

Get copy of Screen::screen1_.

Parameters
[out]outputpreallocated 4-element array
void Gyoto::Screen::getScreen2 ( double  output[]) const

Get copy of Screen::screen2_.

Parameters
[out]outputpreallocated 4-element array
void Gyoto::Screen::getScreen3 ( double  output[]) const

Get copy of Screen::screen3_.

Parameters
[out]outputpreallocated 4-element array
void Gyoto::Screen::inclination ( double  )

Set inclination relative to line-of-sight.

Inclination of z-axis relative to line-of-sight, or inclination of equatorial plane relative to plane of the sky, in radians

void Gyoto::Screen::inclination ( double  ,
const std::string &  unit 
)

Set inclination relative to line-of-sight.

Inclination of z-axis relative to line-of-sight, or inclination of equatorial plane relative to plane of the sky, in specified unit.

double Gyoto::Screen::inclination ( ) const

Get inclination relative to line-of-sight.

Inclination of z-axis relative to line-of-sight, or inclination of equatorial plane relative to plane of the sky, in radians.

double Gyoto::Screen::inclination ( const std::string &  ) const

Get inclination relative to line-of-sight.

Inclination of z-axis relative to line-of-sight, or inclination of equatorial plane relative to plane of the sky, in specified unit.

void Gyoto::Screen::mapPixUnit ( )

Map "pix" and "pixel" to angular pixel width in unit system.

"pix" or "pixel" can then be used in units.

There is only one unit system in Gyoto: "pix" can therefore be registered only for one Screen at a time. See Gyoto::Units.

The unit must later be unmapped with unmapPixUnit().

void Gyoto::Screen::mask ( double const *const  mm,
size_t  resolution = 0 
)

Set mask_ from array.

mm will be copied. mm must be a square resolution x resolution array. If mm==NULL, just deallocate mask_.

bool Gyoto::Screen::operator() ( size_t  ,
size_t   
)

Whether this pixel should be ray-traced.

If mask_ is not set, always true. Else, true for non-zero cells in mask_.

std::ostream& Gyoto::Screen::print ( std::ostream &  ) const

Display.

Debug helper

void Gyoto::Screen::setObserverPos ( const double  pos[4])

Alternative way to set projection.

Beware : paln can not be set this way, setting later other parameters change the observer's coordinates. For observationnal ray-tracing purposes, prefer setProjection().

Parameters
[in]posposition of observer in Screen's coordinate system. Content is copied.
void Gyoto::Screen::unmapPixUnit ( )

Unmap "pix" and "pixel" from unit system.

See also mapPixUnit().

Member Data Documentation

double Gyoto::Screen::euler_[3]
private

Euler angles.

The angles are position angle of the line of nodes (North of East), inclination (0 = face-on), argument of X axis. We use the z-x-z convention. See http://en.wikipedia.org/wiki/Euler_angles

double Gyoto::Screen::freq_obs_
private

Frequency at which the observer observes.

For the quantity Intensity

std::string Gyoto::Screen::mask_filename_
private

Last read or written FITS file.

Used when saving to XML: if the mask was saved or loaded from FITS file, output this file name in the XML.


The documentation for this class was generated from the following file: