defocus-modules/include/defocus/models.h

#ifndef DF_MODELS_H
#define DF_MODELS_H

/** @file models.h
 * @brief Camera models for defocus.
 *
 * Camera models are usually implemented as a function taking an input image and parameters required for the model
 * and produce an output image.
 *
 * Parameters are contained in a parameter struct, because this enables us to something similar to named parameters.
 * We can also do default parameters, by leaving some values set to zero.
 *
 * @code{c}
 * df_thin_lense((df_thin_lense){
 *     .focal_length = 42.f,
 *     .aperture = 21.f,
 *     .focal_distance = 150.f,
 *     .out_distance = 200.f},
 *     in_image,
 *     out_image);
 * @endcode
 *
 * All camera models use the same coordinate space: The camera looks along the positive z-axis in a right-handed
 * coordinate system.  (-> positive y is down, positive x is right.)

 */

#include "image.h"

/** Parameters for the pinhole model. */
typedef struct df_pinhole_params
{
    float focal_length; /**< the cameras focal length in millimeters. */
    float orig_z;       /**< the distance of the input image from the camera. */
    float new_z;        /**< the distance of the generated output image. */
} df_pinhole_params;

/** @brief Simple pinhole camera model.
 *
 * The simplest possible(?) camera model.
 * This function takes an input image at a known distance from the camera and moves it to a new distance.
 *
 * @param params model parameters.
 * @param in_image input image.
 * @param out_image the output image.
 */
DF_API void df_pinhole(df_pinhole_params params, const df_image *in_image, df_image *out_image);

/** Parameters for the thin lense model.
 */
typedef struct df_thin_lense_params
{
    /** The cameras focal length in millimeters. */
    float focal_length;

    /** The aperture size in millimeters */
    float aperture;

    /** The distance between the plane of focus and the camera lens, in millimeters */
    float focal_distance;

    /** The distance between the output image and the camera lens, in millimeters */
    float out_distance;

    /** The number of samples per pixel. Leave at 0 for the default value (64). */
    int sample_count;
} df_thin_lense_params;

/** @brief Thin-lense model.
 *
 * @param params model parameters
 * @param in_image input image
 * @param out_image the output image.
 */
DF_API void df_thin_lense(df_thin_lense_params params, const df_image *in_image, df_image *out_image);

#endif