usage.rst

Using libprofit

From the command-line

libprofit ships with a command-line utility profit-cli that reads the model and profile parameters from the command-line and generates the corresponding image. It supports all the profiles supported by libprofit, and can output the resulting image as text values, a binary stream, or as a simple FITS file.

Run profit-cli -h for a full description on how to use it, how to specify profiles and model parameters, and how to control its output.

Programatically

As it name implies, libprofit also ships a shared library exposing an API that can be used by any third-party application. This section gives a brief overview on how to use this API. For a full reference please refer to api.

cpp

cpp

profit

At the core of libprofit sits Model. This class holds all the information needed to generate an image. Different profiles (instances of Profile) are appended to the model, which is then evaluated.

The basic usage pattern then is as follows:

1. Add the profit include:

   #include <profit/profit.h>

2. Initialize the library with the init function. This needs to be called only once in your program:

   profit::init();

3. First obtain a model instance that will generate profile images for a given width and height:

   profit::Model model(width, height);

4. Create a profile. For a list of supported names see profiles; if you want to support a new profile see new_profile. If an unknown name is given an invalid_parameter exception will be thrown:

   profit::ProfilePtr sersic_profile = model.add_profile("sersic");

5. Customize your profile. To set the different parameters on your profile call Profile::parameter with the parameter name and value:

   sersic_profile.parameter("xcen", 34.67);
   sersic_profile.parameter("ycen", 9.23);
   sersic_profile.parameter("axrat", 0.345);
   sersic_profile.parameter("nser=3.56");
   // ...

   A complete list of parameters can be found on and profiles and api.

6. Repeat the previous two steps for all profiles you want to include in your model.

7. Evaluate the model simply run:

   profit::Image result = model.evaluate();

8. If the resulting image needs to be cropped (see convolution.image_cropping for full details) an additional argument needs to be passed to Model::evaluate to receive the offset at which cropping needs to be, like this:

   profit::Point offset;
   profit::Image result = model.evaluate(offset);
   profit::Image cropped_image = result.crop({width, height}, offset);

9. If there are have been errors while generating the image an invalid_parameter exception will be thrown by the code, so users might want to use a try/catch statement to identify these situations:

   try {
       auto result = model.evaluate();
   } catch (profit::invalid_parameter &e) {
       cerr << "Oops! There was an error evaluating the model: " << e.what() << endl;
   }

10. When the model is destroyed the underlying profiles are destroyed as well.

11. When you are finished using the library, call the finish function:

    profit::finish();

To illustrate this process, refer to the following figure: