Model class

class Model

The overall model to be created

The model includes the width and height of the image to produce, as well as the resolution to use when performing calculations. Having resolution allows us to specify pixel position with decimal places; e.g., the center point for a given profile.

Public Functions

Model(unsigned int width = 0, unsigned int height = 0)

Constructor

It creates a new model to which profiles can be added, and that can be used to calculate an image.

explicit Model(Dimensions dimensions): Like Model(unsigned int, unsigned int), but accepting a Dimensions object.

ProfilePtr add_profile(const std::string &profile_name)

Creates a new profile for the given name and adds it to the given model. On success, the new profile is created, added to the model, and its reference is returned for further customization. If a profile with the given name is not supported an invalid_parameter exception is thrown.

Parameters:: profile_name – The name of the profile that should be created
Returns:: A pointer to the new profile that corresponds to the given name

bool has_profiles() const

Whether this model contains any profiles or not.

Returns:: true if this module contains at least one profile, false otherwise

Image evaluate(Point &offset_out = NO_OFFSET)

Calculates an image using the information contained in the model. The result of the computation is returned as an Image, which may be of a different size from the one originally requested if the user set this model’s crop property to false (via set_crop). If users want to know the offset at which the image resulting of evaluating this Model with its configured parameters is with respect to the Image value returned by this method, hen they must provide a Point in offset_out, which will contain the information after the method returns.

In other words, the Image returned by this method can be bigger than the Model’s dimensions if the user requested this Model to return a non-cropped Image.

Parameters:: offset_out – The potential offset with respect to the image returned by this method at which the image of this Model’s dimensions can be found.
Returns:: The image created by libprofit.

void evaluate(Image &image, Point &offset_out = NO_OFFSET): Like evaluate(Point &), but the user provides an Image to write data on.

Dimensions get_drawing_dimensions() const

Returns the dimensions that this model will need to use internally when drawing profile images, considering any effects like PSF padding, finesampling, etc.

This function can be useful to pre-allocate an Image of this size and use it with evaluate(Image &, Point &).

Returns:: The dimensions of the Image this Model will internally draw pixels on.

std::map<std::string, std::shared_ptr<ProfileStats>> get_stats() const

Return a map of all profile statistics.

Returns:: A map indexed by profile name with runtime statistics

inline void set_dimensions(const Dimensions &dimensions)

Sets the dimensions of the model image to generate

Parameters:: dimensions – The dimensions of the model image to generate

inline void set_finesampling(unsigned int finesampling): Sets the finesampling factor to use in this Model

inline void set_psf(const Image &psf)

Sets the PSF image that this Model should use

Parameters:: psf – The PSF image that this Model should use

inline void set_psf(Image &&psf)

See also

set_psf(const Image &psf)

inline void set_image_pixel_scale(const PixelScale &scale)

Sets the pixel scale of the generated model image.

The image scale is the width (and height) of a single pixel in image coordinates.

Parameters:: scale – The pixel scale of the model image

inline PixelScale get_image_pixel_scale() const

Returns the pixel scale of the generated model image.

See also

set_image_pixel_scale(double, double)

Returns:: the image scale of the generated model image

inline void set_psf_pixel_scale(const PixelScale &scale)

Sets the PSF’s pixel scale.

See also

set_image_pixel_scale(double, double)

Parameters:: scale – The pixel scale of the PSF

inline PixelScale get_psf_pixel_scale() const

Returns the pixel scale of the PSF.

See also

set_psf_pixel_scale(double, double)

Returns:: the image scale of the generated model image

inline void set_magzero(double magzero)

Sets the base magnitude to be applied to all profiles.

Parameters:: magzero – The base magnitude to be applied to all profiles.

inline void set_mask(const Mask &mask)

Set the calculation mask. If given it must be the same size of the expected output image, and its values are used to limit the profile calculation only to a given area (i.e., those cells where the value is true).

Parameters:: mask – The mask to use to limit profile calculations

inline void set_mask(Mask &&mask)

See also

set_mask(const Mask &mask)

inline void set_adjust_mask(bool adjust_mask)

Sets whether the mask given by the user should be automatically adjusted in order to preserve flux during convolution or not. By default masks are adjusted as necessary, but if users have a pre-adjusted Mask (obtained via adjust(Mask &, const Dimensions &, const Image &, unsigned int)) and pass that to the Model, then they need to indicate that no further adjustment in necessary

Parameters:: adjust_mask – Whether this model should internally adjust the mask given by the user or not.

inline void set_convolver(ConvolverPtr convolver): Set a convolver for this Model. A convolver is an object used to carry out the convolution, if necessary. If a convolver is present before calling evaluate then it is used. If missing and one is required, a new one is created internally.

inline void set_crop(bool crop)

Set the cropping flag.

Due to their internal workings, some convolvers produce actually bigger which are (by default) cropped to the size of the original images created by the profiles. If this option is set to true, then the result of the convolution will not be cropped, meaning that the result of the model evaluation will be bigger than what was originally requested.

Parameters:: crop – Whether this model returns a cropped image (default) or not to the user.

inline void set_dry_run(bool dry_run)

Sets the dry run flag. The dry run flag determines whether the actual evaluation of profiles should be skipped or not; if skipped profile validation still takes place.

Parameters:: dry_run – Whether evaluation of profiles should take place (default) or not

inline void set_return_finesampled(bool return_finesampled)

Set the return finesampled flag.

When users set a finesampling factor on the model (via set_finesampling()) the image calculated by this model will have bigger dimensions than those originally set in the Model. This flag controls whether this bigger image should be returned (default behavior), or whether a smaller version of the image with dimensions equals to the ones requested (plus any padding introduced by convolution) should be returned. If a smaller image is returned, the total flux of the image is still preserved.

Parameters:: return_finesampled – Whether this model should return finesampled images as-is (true) or if they should be downsampled to match the original model dimensions.

inline void set_omp_threads(unsigned int omp_threads)

Sets the maximum number of OpenMP threads to use to evaluate the profiles contained in this model. Anything less of equals to 1 means that no OpenMP support has been requested.

Parameters:: omp_threads – the number of OpenMP threads to use for profile evaluation. OpenMP is used only if two or more threads are requested.

inline unsigned int get_omp_threads()

Returns the number of OpenMP threads this Model has been configured to work with

Returns:: the number of OpenMP threads this Model has been configured to work with

Public Static Functions

static void adjust(Mask &mask, const Dimensions &dims, const Image &psf, unsigned int finesampling = 1)

Modifies mask in the same way that it would be modified internally by a Model object in order to preserve flux during the convolution step of the Model evaluation.

See also

set_adjust_mask(bool)

Parameters:

mask – The mask to be modified.
dims – The dimensions of the Model
psf – The PSF to be used during Model convolution
finesampling – The finesampling factor to be used by the Model

Public Static Attributes

static Point NO_OFFSET: The Point object that indicates that users don’t want to retrieve back the potential image offset when calling evaluate(Point &)