Ray-tracing scene. More...

#include <GyotoScenery.h>

Inheritance diagram for Gyoto::Scenery:

Public Member Functions
	Scenery ()
	Set everything to defaults.

	Scenery (const Scenery &o)
	Copy constructor.

Scenery *	clone () const
	Cloner.

	Scenery (SmartPointer< Metric::Generic >, SmartPointer< Screen >, SmartPointer< Astrobj::Generic >)
	Constructor setting Scenery::gg_, Scenery::screen_, and Scenery::obj_. More...

SmartPointer< Metric::Generic >	getMetric ()
	Get Scenery::gg_.

void	setMetric (SmartPointer< Metric::Generic >)
	Set Scenery::gg_. More...

SmartPointer< Screen >	getScreen ()
	Get Scenery::screen_.

void	setScreen (SmartPointer< Screen >)
	Set Scenery::screen_. More...

SmartPointer< Astrobj::Generic >	getAstrobj ()
	Get Scenery::obj_.

void	setAstrobj (SmartPointer< Astrobj::Generic >)
	Set Scenery::obj_. More...

double	getDelta () const
	Get default step in geometrical units.

double	getDelta (const std::string &unit) const
	Get default step in specified units.

void	setDelta (double)
	set default step in geometrical units

void	setDelta (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	getTmin () const
	Get Scenery::tmin_.

double	getTmin (const std::string &unit) const
	Get Scenery::tmin_ in specified unit.

void	setTmin (double)
	Set Scenery::tmin_.

void	setTmin (double, const std::string &unit)
	Set Scenery::tmin_ in specified unit.

void	adaptive (bool mode)
	Set Scenery::adaptive_.

bool	adaptive () const
	Get Scenery::adaptive_.

void	maxiter (size_t miter)
	Set Scenery::maxiter_.

size_t	maxiter () const
	Get Scenery::maxiter_.

void	setNThreads (size_t)
	Set nthreads_;.

size_t	getNThreads () const
	Get nthreads_;.

void	setIntensityConverter (std::string unit)
	Set Scenery::intensity_converter_.

void	setSpectrumConverter (std::string unit)
	Set Scenery::spectrum_converter_.

void	setBinSpectrumConverter (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< Scenery >	Subcontractor (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< Metric::Generic >	gg_

SmartPointer< Screen >	screen_

SmartPointer< Astrobj::Generic >	obj_

bool	adaptive_
	Whether integration should use adaptive delta.

double	delta_

Gyoto::Quantity_t	quantities_
	Quantities to compute. More...

Gyoto::Photon	ph_
	Cached Photon. More...

double	tmin_
	Time limit for the integration (geometrical units) 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:

a Metric: used in Astrobj, Screen and Photon;
a Screen: sets the field-of-view, the position of the camera, the observation time, and the Spectrometer;
an Astrobj: light emitter.

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). A value of the integration step for the Photon's trajectory can be specified in Delta. It will be used as the initial step, which is adaptive. Possible Quantities:

Intensity: the intensity that reaches the object, integrated over the line-of-sight;
EmissionTime: date of emission;
MinDistance: minimum distance between the Photon reaching each pixel and the Astrobj;
FirstDistMin: last closest approach between Photon and Astrobj;
Redshift;
ImpactCoords: 8-coordinates of the object and photon at impact;
Spectrum: I_ν computed at various values frequencies, corresponding to the Screen's Spectrometer.
BinSpectrum: ∫_ν₁^ν₂I_νdν computed between various (ν₁, ν₂ pairs corresponding to the Screen's Spectrometer. This is what a physical spectrometer measures.

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.

Thus a fully populated Scenery XML looks like that:

* <?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>
*
*  <Delta> 1. </Delta>
*
*  <NThreads> 2 </NThreads>  
*
* </Scenery>
* 

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::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::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

setPropertyConverters() to set the converters in *data;
Astrobj::Properties::init() to initialize each cell in *data;
Astrobj::Properties::operator++() to step through the arrays in *data.

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,jmax	First and last rows and columns in Scenery::screen_ to compute
[in,out]	data	Pointer to a preallocated Astrobj::Properties instance which sets which quantities must be computed and where to store the output.
[in]	impactcoords	Optional 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::setAstrobj ( SmartPointer< Astrobj::Generic > )

Set Scenery::obj_.

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

void Gyoto::Scenery::setMetric ( SmartPointer< Metric::Generic > )

Set Scenery::gg_.

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

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

quant

Bitwise OR of desired quantities, e.g.

GYOTO_QUANTITY_SPECTRUM | GYOTO_QUANTITY_MIN_DISTANCE

void Gyoto::Scenery::setRequestedQuantities ( std::string squant )

Set Scenery::quantities_ from string.

Parameters

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

void Gyoto::Scenery::setScreen ( SmartPointer< Screen > )

Set Scenery::screen_.

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

Member Data Documentation

double Gyoto::Scenery::delta_

protected

Default integration step for the photons

SmartPointer<Metric::Generic> Gyoto::Scenery::gg_

protected

The Metric, or stage, for this scenery.

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.

SmartPointer<Astrobj::Generic> Gyoto::Scenery::obj_

protected

The astrophysical emitting light in this scenery... the actor.

Gyoto::Photon Gyoto::Scenery::ph_

protected

Cached Photon.

Used internally to not always reallocate memory when operator() is called.

Gyoto::Quantity_t Gyoto::Scenery::quantities_

protected

Quantities to compute.

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

* GYOTO_QUANTITY_INTENSITY | GYOTO_QUANTITY_EMISSIONTIME | ...

*

SmartPointer<Screen> Gyoto::Scenery::screen_

protected

Screen, the camera for this scenery.

double Gyoto::Scenery::tmin_

protected

Time limit for the integration (geometrical units)

Computation does not go back before tmin_. Default is -DBL_MAX. tmin_ is always expressed in geometrical units, it is essentially a tuning parameter for the ray-tracing process. tmin should be chosen to always be longer than the distance between the screen and the object.

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

GyotoScenery.h

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation