A camera object is a plane with \(N_y\times N_z\) pixels. By convention, the camera plane reference axes are Y (horizontal) and Z (vertical). The X axis is perpendicular to the camera plane. Pixels are indexed from 0 to \(N_y-1\) from left to right and from 0 to \(N_z-1\).
Camera object.
Pixels are indexed by \((i,j)\) in the \(yz\) matrix. The properties of pixels are managed with matrices or the so-called "pixel maps". This class implements 4 pixel maps:
an intrinsic dark noise level map, defined by a mean \(\Lambda_{ij}\) and a standard deviation \(\lambda_{ij}\) value for each pixel.
an intrinsic read noise level map, defined by a mean \(\Xi_{ij}\) and a standard deviation \(\xi_{ij}\) value for each pixel.
a raw amplitude \(A_{ij}\) map which is encoded over a given number of bits.
a calibration factor or gain \(G_{ij}\) map used to transform amplitudes (after noise subtraction) in energies [keV].
In addition, the camera CCD is also described by several parameters:
an orientation in space, managed by the Rotation class.
A sequence of camera objects can be saved in a TTree structure and eventually saved to disk. After opening a TFile, the following functions should be called:
The camera position must be defined in space. The reference frame of the camera is \(\cal{R}\), where the \(x\) axis is the pointing axis and the camera is located in the \(yOz\) plane. The Earth celestial reference frame is noted \(\cal{R}'\). The rotation between the camera reference frame and the Earth reference frame is managed by the Rotation class from which the Camera class inherits. Intrinsic Euler angles, \((\alpha, \beta, \gamma)\) are use to track the camera reference frame in the Earth reference frame. These angles must be set with Rotation::SetAlphaBetaGamma() before taking pictures.
Camera (blue) and Earth celestial (black) reference frames. The rotation to change the system of coordinates is given by the Euler angles and is represented in green.
The pixel intrinsic amplitude noise can be decomposed into two contributions: \(N_{ij} = D_{ij} + R_{ij}\). The dark noise component \(D_{ij}\) measures the amplitude induced by statistical fluctuations in thermal electron production. It is modeled with a Gaussian statistic characterized by a per-pixel mean value \(\Lambda_{ij}\) and a standard deviation \(\lambda_{ij}\). Both parameters are functions of time and can be used to account for temperature variations. Similarly, the read noise amplitude \(R_{ij}\) inherent to the camera reading electronics is parameterized by a per-pixel mean value \(\Xi_{ij}\) and a standard deviation \(\xi_{ij}\), both of which are time dependent. \(\Lambda_{ij}\) and \(\lambda_{ij}\) are saved in the dark noise map. \(\Xi_{ij}\) and \(\xi_{ij}\) are saved in the read noise map. The process of taking a picture starts with generating pixel noise \(N_{ij}\). For each pixel, the dark and read noise amplitudes \(D_{ij}\) and \(R_{ij}\) are drawn from a Gaussian distribution with parameters defined above.
The noise parameters can be used to define corrupted pixels. For example a pixel is dead if \(\Lambda_{ij}=\lambda_{ij}=\Xi_{ij}=\xi_{ij}=0\).
Photon generation
Photons can be added on top of the camera noise with AddPhoton(). The photon energy is distributed using a two-dimensional Gaussian distribution centered on the photon impact position. The width of the Gaussian functions can be set with SetPhotonResolution().
Initializes the TH2 containers to store the camera pixel parameters. Four camera maps are created:
a pixel raw amplitude map. The range of pixel raw amplitudes is limited by the number of bits specified by the user. The maximum number of bits is 16. By default, all pixel amplitudes are set to 0.
a pixel dark noise amplitude map. By default, the noise values for all pixels are drawn from a Gaussian distribution, the parameters of which are set with the SetPixelDistributions() function.
a pixel read noise amplitude map. By default, the noise values for all pixels are drawn from a Gaussian distribution, the parameters of which are set with the SetPixelDistributions() function.
a pixel gain map (set to 1 for all pixels by default). The gain is used to transform the pixel raw amplitude to a calibrated energy [keV]: \(E_{ij} = G_{ij}\times (A_{ij}-N_{ij})\).
A cosmic ray is usually a very energetic particle. The interaction with the camera is simulated as a straight track through the camera pixels. The track is entirely determined by the incoming direction of the particle \((\theta,\varphi)\). The entry point \((y_c,z_c)\) must be given, using the camera intrinsic coordinates. From this point a straight line is used to identify all the illuminated pixels. For each pixel, a fix amount of energy (see SetCosmicRayEnergyLoss()) is transfered from the particle to the pixels, and is distributed using a 2D Gaussian parameterized with SetPhotonResolution(). If all the available energy has been consumed, the track stops.
Geometry of a cosmic ray crossing the camera plane.
Parameters
[in]
aEnergy
Photon energy in keV.
[in]
aY
Entry position in the Y direction. Use the camera intrinsic coordinates: from 0 to 1.
[in]
aZ
Entry position in the Z direction. Use the camera intrinsic coordinates: from 0 to 1.
The incoming photon is defined by an energy (in keV) and a YZ position in the detector plane. A 2D normalized Gaussian distribution is centered on the photon position. This Gaussian distribution is used to distribute the energy over the pixels. All the photon energy is distributed over the pixels. The Gaussian size must be previously set with SetPhotonResolution().
The photon energy is only distributed over \(\pm 15 \sigma\) around the central position. The energy outside this limit is considered to be negligible. This can be a problem for very energetic photons.
If both the dark and read noise standard deviation value are set to 0, the pixel is considered to be frozen. In that case the photon energy in this pixel is not injected.
The pixel energy is converted to a raw amplitude using the gain map: \(A_{ij}=E_{ij}/G_{ij}\).
The pixel amplitude is added to the pixel.
When the photon is associated to a Source, a source index and a particle index can be provided to associate the hit to the source.
Warning
If the number of hits for a given picture reaches CAMERA_NHITMAX, the hit will not be saved in the tree (see TreeFill()).
Parameters
[in]
aEnergy
Photon energy in keV.
[in]
aY
Photon central position in the Y direction. Use the camera intrinsic coordinates: from 0 to 1.
[in]
aZ
Photon central position in the Z direction. Use the camera intrinsic coordinates: from 0 to 1.
The pixel of given indices in the amplitude map is incremented by a given value. If the pixel indices are out-of-range, the map overflows are incremented. If the pixel amplitude is, or gets, saturated, this function has no effect.
Fills the raw amplitude map with intrinsic pixel noise.
The noise amplitude value of a given pixel is the sum of 2 contributions: the dark and read noises. Each component is randomly drawn from a Gaussian distribution defined by the corresponding noise maps.
Warning
If the pixel amplitude value is negative, it is automatically forced to 0. This behavior can create a small bias in the noise distribution compared to input noise amplitude maps.
The computed amplitude value is used to fill both the pixel value and the pixel error of the amplitude map. This way, the pixel noise level value is saved in the error container.
This parameter controls how a cosmic ray looses energy when crossing the camera plane. When a cosmic ray travels through a pixel, it looses a fix amount of energy.
Parameters
[in]
aEnergyLoss
Fix energy amount lost by the cosmic ray when crossing 1 pixel in keV.
The input histogram is used to fill a given camera map. Each bin represents a pixel. Both the bin content and error are copied locally. The histogram X (Y) axis is interpreted as the Y (Z) axis of the camera.
Sets the spatial resolution to inject photons in the camera frame.
The photon energy is distributed in the camera pixels following a 2D Gaussian law. This function sets the width of the Gaussian distributions in the Y and Z directions. This is measured as a fraction of pixels.
Parameters
[in]
aPixelResY
Gaussian sigma in the Y direction measured as a pixel fraction.
[in]
aPixelResZ
Gaussian sigma in the Z direction measured as a pixel fraction.
Sets a Gaussian distribution for a given pixel map.
A given pixel map can be filled using a Gaussian statistic for each pixel. The pixel content is drawn from a Gaussian distribution parameterized by a mean value and a sigma value. These 2 parameters (mean and sigma) can also be drawn from a Gaussian distribution. This function is used to parameterized the 2 Gaussian distributions from which the mean and sigma values are drawn.
Note
I know, it is a bit confusing!
If one parameter is set to a negative value, a default value is used: