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

Ray-tracing scene. More...

#include <GyotoScenery.h>

Inheritance diagram for Gyoto::Scenery:
Gyoto::SmartPointee

Public Member Functions

 Scenery ()
 Set everything to defaults.
 
 Scenery (const Scenery &o)
 Copy constructor.
 
Sceneryclone () const
 Cloner.
 
 Scenery (SmartPointer< Metric::Generic >, SmartPointer< Screen >, SmartPointer< Astrobj::Generic >)
 Constructor setting Scenery::gg_, Scenery::screen_, and Scenery::obj_. More...
 
SmartPointer< Metric::Genericmetric () const
 Get ph_.Worldline::metric_.
 
void metric (SmartPointer< Metric::Generic >)
 Set Scenery::gg_. More...
 
SmartPointer< Screenscreen () const
 Get Scenery::screen_.
 
void screen (SmartPointer< Screen >)
 Set Scenery::screen_. More...
 
SmartPointer< Astrobj::Genericastrobj () const
 Get ph_.obj_.
 
void astrobj (SmartPointer< Astrobj::Generic >)
 Set ph_.obj_. More...
 
SmartPointer< PhotonclonePhoton () const
 Clone the internal Photon.
 
double delta () const
 Get default step in geometrical units.
 
double delta (const std::string &unit) const
 Get default step in specified units.
 
void delta (double)
 set default step in geometrical units
 
void delta (double, const std::string &unit)
 set default step in specified units
 
void setRequestedQuantities (Quantity_t quant)
 Set Scenery::quantities_. More...
 
void setRequestedQuantities (std::string squant)
 Set Scenery::quantities_ from string. More...
 
Quantity_t getRequestedQuantities () const
 Get Scenery::quantities_.
 
std::string getRequestedQuantitiesString () const
 Get a string representation of Scenery::quantities_.
 
size_t getScalarQuantitiesCount () const
 Get number of requested quantities of scalar nature. More...
 
double tMin () const
 Get ph_.tmin_.
 
double tMin (const std::string &unit) const
 Get ph_.tmin_ in specified unit.
 
void tMin (double)
 Set ph_.tmin_.
 
void tMin (double, const std::string &unit)
 Set ph_.tmin_ in specified unit.
 
void adaptive (bool mode)
 Set ph_.adaptive_.
 
bool adaptive () const
 Get ph_.adaptive_.
 
void integrator (std::string type)
 Passed to ph_.
 
std::string integrator () const
 Passed to ph_.
 
double deltaMin () const
 Passed to ph_.
 
void deltaMin (double h1)
 Passed to ph_.
 
double deltaMax () const
 Passed to ph_.
 
void deltaMax (double h1)
 Passed to ph_.
 
double deltaMaxOverR () const
 Passed to ph_.
 
void deltaMaxOverR (double t)
 Passed to ph_.
 
void absTol (double)
 Passed to ph_.
 
double absTol () const
 Passed to ph_.
 
void relTol (double)
 Passed to ph_.
 
double relTol () const
 Passed to ph_.
 
void secondary (bool sec)
 Set ph_.secondary_.
 
bool secondary () const
 Get ph_.secondary_.
 
void maxiter (size_t miter)
 Set ph_.maxiter_.
 
size_t maxiter () const
 Get ph_.maxiter_.
 
void nThreads (size_t)
 Set nthreads_;.
 
size_t nThreads () const
 Get nthreads_;.
 
void intensityConverter (std::string unit)
 Set Scenery::intensity_converter_.
 
void spectrumConverter (std::string unit)
 Set Scenery::spectrum_converter_.
 
void binSpectrumConverter (std::string unit)
 Set Scenery::binspectrum_converter_.
 
void setPropertyConverters (Gyoto::Astrobj::Properties *prop)
 Copy converters to Astrobj::Properties instance. More...
 
void rayTrace (size_t imin, size_t imax, size_t jmin, size_t jmax, Astrobj::Properties *data, double *impactcoords=NULL)
 Perform ray-tracing for a square area on Screen. More...
 
void operator() (size_t i, size_t j, Astrobj::Properties *data, double *impactcoords=NULL, Photon *ph=NULL)
 Ray-trace a single pixel in Scenery::screen_. More...
 
void fillElement (FactoryMessenger *fmp)
 Fill XML section. More...
 

Static Public Member Functions

static SmartPointer< ScenerySubcontractor (Gyoto::FactoryMessenger *)
 Instanciate Scenery from an XML description.
 

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.
 

Protected Attributes

SmartPointer< Screenscreen_
 
double delta_
 
Gyoto::Quantity_t quantities_
 Quantities to compute. More...
 
Gyoto::Photon ph_
 Template Photon. More...
 
size_t nthreads_
 Number of parallel threads to use in rayTrace() More...
 
Gyoto::SmartPointer
< Gyoto::Units::Converter
intensity_converter_
 See Astrobj::Properties::intensity_converter_.
 
Gyoto::SmartPointer
< Gyoto::Units::Converter
spectrum_converter_
 See Astrobj::Properties::intensity_converter_.
 
Gyoto::SmartPointer
< Gyoto::Units::Converter
binspectrum_converter_
 See Astrobj::Properties::intensity_converter_.
 
size_t maxiter_
 Maximum number of iterations when integrating.
 

Friends

class Gyoto::SmartPointer< Gyoto::Scenery >
 

Detailed Description

Ray-tracing scene.

An Scenery contains:

In addition, Quantities may be specified (or the default Quantity will be produced: generally Intensity). Not all Astrobj implement all Quantities. The order in which Quantities are listed is not relevant (it is not stored). Possible Quantities:

In addition, it is possible to ray-trace an image using several cores on a single machine (if Gyoto has been compiled with POSIX threads support). The number of threads can be specified using NThreads entity. Setting NThreads to 0 is equivalent to setting it to 1. Beware that setting NThreads to a number higher than the actual number of cores available on the machine usually leads to a decrease in performance.

Finally, Scenery accepts a number of numerical tuning parameters that are passed directly to the underlying photons (actually, the Scenery object holds a Photon instance which stores many parameters, including the Metric and Astrobj): Adaptive/NonAdaptive, Delta, MinimumTime, MaxIter, PrimaryOnly.

Thus a fully populated Scenery XML looks like that (the values are examples, they are not necessary the default nor the best or even good values):

<?xml version="1.0" encoding="UTF-8"
standalone="no"?> <Scenery>
<Metric kind = "MetricKind">
<MetricProperties/>
</Metric>
<Screen>
<ScreenProperties/>
</Screen>
<Astrobj kind = "AstrobjKind">
<AstrobjParameters/>
</Astrobj>
<Quantities> Spectrum Intensity ...</Quantities>
<NThreads> 2 </NThreads>
Next come the numerical tuning parameters:
Integration step, initial in case of adaptive, reset for
for each ray being traced:
<Delta unit="geometrical"> 1 </Delta>
Adaptive or NonAdaptive:
<Adaptive/>
The integrator to use for integrating the photons:
<Integrator>runge_kutta_fehlberg78</Integrator>
The "Legacy" integrator is coded in
Metric::Generic::myrk4_adaptive(), may be re-implemented in othe
metrics, and therefore takes its tuning parameters in the Metric
section. The other integrators (runge_kutta_fehlberg78,
runge_kutta_cash_karp54, runge_kutta_dopri5,
runge_kutta_cash_karp54_classic) accept the following tuning
parameters, directly in the Scenery section:
Absolute and relative tolerance for the adaptive step:
<AbsTol>1e-11</AbsTol>
<RelTol>1e-11</RelTol>
Normally, you should not need to tune the other three. If you need
to, try using a higher order integrator:
maximum integration step:
<DeltaMax> 100 </DeltaMax>
delta_max/R where R is the current distance to the origin:
<DeltaMaxOverR> 0.1 </DeltaMaxOverR>
minimum step:
<DeltaMin>1e-20</DeltaMin>
A few safe-guards to avoid infinite loops:
Maximum number of iterations for each ray:
<Maxiter> 1000000 </Maxiter>
Minimum date a photon may reach backwards in time:
<MinimumTime unit="yr">25e3</MinimumTime>
This one is an experimental, poorly specified feature:
<!--PrimaryOnly/-->

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().

Constructor & Destructor Documentation

Gyoto::Scenery::Scenery ( SmartPointer< Metric::Generic ,
SmartPointer< Screen ,
SmartPointer< Astrobj::Generic  
)

Constructor setting Scenery::gg_, Scenery::screen_, and Scenery::obj_.

To ensure consistency, the Metric will be forcibly attached to the Screen and to the Astrobj (if they are not NULL).

Member Function Documentation

void Gyoto::Scenery::astrobj ( SmartPointer< Astrobj::Generic )

Set ph_.obj_.

The Metric attached to the Scenery will be attached to the Astrobj

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

Fill XML section.

Akin to Astrobj::Generic::fillElement or Metric::Generic::fillElement for instance.

size_t Gyoto::Scenery::getScalarQuantitiesCount ( ) const

Get number of requested quantities of scalar nature.

This is all quantities except Spectrum, BinSpectrum and ImpactCoords.

void Gyoto::Scenery::metric ( SmartPointer< Metric::Generic )

Set Scenery::gg_.

The provided Metric will also be atached to the Screen and the Astrobj.

void Gyoto::Scenery::operator() ( size_t  i,
size_t  j,
Astrobj::Properties data,
double *  impactcoords = NULL,
Photon ph = NULL 
)

Ray-trace a single pixel in Scenery::screen_.

Almost identical to rayTrace(), but for a single pixel.

If ph is passed, it is assumed to have been properly initialized (with the right metric and astrobj etc.) already. Else, use &Scenery::ph_.

void Gyoto::Scenery::rayTrace ( size_t  imin,
size_t  imax,
size_t  jmin,
size_t  jmax,
Astrobj::Properties data,
double *  impactcoords = NULL 
)

Perform ray-tracing for a square area on Screen.

For each Scenery::screen_ pixel in the square area limited by imin, imax, jmin and jmax, launch a Photon back in time to compute the various quantities.

At this time, the computed quantities depend on on the pointers in *data which are not NULL.

rayTrace() uses

data must have been instanciated prior to calling rayTrace and the various pointers in *data must be NULL or point to the first cell in an array of size at least Screen::npix_ squared.

If Scenery::nthreads_ is ≥2 and Gyoto has been compiled with pthreads support, rayTrace() will use Scenery::nthreads_ threads and launch photons in parallel. This works only if the Astrobj::Generic::clone() and Metric::Generic::clone() methods have been properly implemented for the specific astrobj and metric kind, and if they are both thread-safe. At the moment, unfortunately, Lorene metrics are known to not be thread-safe.

Parameters
[in]imin,imax,jmin,jmaxFirst and last rows and columns in Scenery::screen_ to compute
[in,out]dataPointer to a preallocated Astrobj::Properties instance which sets which quantities must be computed and where to store the output.
[in]impactcoordsOptional pointer to an array of pre-computed impact coordinates. If impactcoords is provided, rayTracing is skipped and the quantities in *data are fill assuming that the impact coordinates are correct. This only makes sense in optically thick mode, when ray-tracing several sceneries for which the shape of the object is identical but their emission distributions are not. impactcoords can be computed using the ImpactCoords quantity.
void Gyoto::Scenery::screen ( SmartPointer< Screen )

Set Scenery::screen_.

The Metric attached to the Scenery will be attached to the Screen

void Gyoto::Scenery::setPropertyConverters ( Gyoto::Astrobj::Properties prop)

Copy converters to Astrobj::Properties instance.

Copy Scenery::intensity_converter_, Scenery::spectrum_converter_ and Scenery::binspectrum_converter_ to there alter ego in *prop.

void Gyoto::Scenery::setRequestedQuantities ( Quantity_t  quant)

Set Scenery::quantities_.

Parameters
quantBitwise OR of desired quantities, e.g.
void Gyoto::Scenery::setRequestedQuantities ( std::string  squant)

Set Scenery::quantities_ from string.

Parameters
squantComa-separated list of quantities, e.g. "Spectrum MinDistance". The order is not relevant.

Member Data Documentation

double Gyoto::Scenery::delta_
protected

Default integration step for the photons

size_t Gyoto::Scenery::nthreads_
protected

Number of parallel threads to use in rayTrace()

When compiled with libpthread, Scenery::rayTrace() may compute several points of the image in parallel threads. This is the number of threads to use.

Gyoto::Photon Gyoto::Scenery::ph_
protected

Template Photon.

Used internally to not always reallocate memory when operator() is called and to store all the parameters which affect the integration, except delta_.

Gyoto::Quantity_t Gyoto::Scenery::quantities_
protected

Quantities to compute.

Bitwise OR of quantities that will be computed, for instance:

SmartPointer<Screen> Gyoto::Scenery::screen_
protected

Screen, the camera for this scenery.


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