simplify core API (#178)

* simplify core API

Signed-off-by: Anton Dukhovnikov <[email protected]>

* address review issues

Signed-off-by: Anton Dukhovnikov <[email protected]>

* address review issues

Signed-off-by: Anton Dukhovnikov <[email protected]>

* Update src/rawtoaces_core/rawtoaces_core.cpp

Co-authored-by: Aleksandr Motsjonov <[email protected]>
Signed-off-by: Anton Dukhovnikov <[email protected]>

---------

Signed-off-by: Anton Dukhovnikov <[email protected]>
Co-authored-by: Aleksandr Motsjonov <[email protected]>

Author: antond-weta

include/rawtoaces/image_converter.h

@@ -15,9 +15,9 @@ namespace util
 /// directory, create an entry in `batches` and fill it with the file names
 /// from that directory. If the `path` is a file, add its name to the first
 /// entry in `batches`.
-/// - parameter path: path to a file or directory to process.
-/// - parameter batches: the collection of batches to fill in.
-/// - returns `false` if the file or directory requested in `path` does not
+/// @param path path to a file or directory to process.
+/// @param batches the collection of batches to fill in.
+/// @result `false` if the file or directory requested in `path` does not
 /// exist.
 bool collect_image_files(
     const std::string &path, std::vector<std::vector<std::string>> &batches );
@@ -128,8 +128,7 @@ class ImageConverter
     /// The parser object can be amended by the calling code afterwards if
     /// needed. This method is optional, all of the settings above can be
     /// modified directly.
-    /// - parameter arg_parser:
-    ///    The command line parser object to be updated.
+    /// @param arg_parser The command line parser object to be updated.
     void init_parser( OIIO::ArgParse &arg_parser );
 
     /// Initialise the converter settings from the command line parser object.
@@ -138,10 +137,8 @@ class ImageConverter
     /// `OIIO::ArgParse::parse_args()`.
     /// This method is optional, all of the settings above can be modified
     /// directly.
-    /// - parameter arg_parser:
-    ///    the command line parser object
-    /// - returns
-    ///    `true` if parsed successfully
+    /// @param arg_parser the command line parser object
+    /// @result `true` if parsed successfully
     bool parse_parameters( const OIIO::ArgParse &arg_parser );
 
     /// Collects all illuminants supported by this version.
@@ -156,13 +153,13 @@ class ImageConverter
     /// This method loads the metadata from the given image file and
     /// initialises the options to give the OIIO raw image reader to
     /// decode the pixels.
-    /// - parameter input_filename:
+    /// @param input_filename
     ///    A file name of the raw image file to read the metadata from.
-    /// - parameter options:
+    /// @param options
     ///    Conversion hints to be passed to OIIO when reading an image file.
     ///    The list can be pre- or post- updated with other hints, unrelated to
     ///    the rawtoaces conversion.
-    /// - returns
+    /// @result
     ///    `true` if configured successfully.
     bool configure(
         const std::string &input_filename, OIIO::ParamValueList &options );
@@ -171,13 +168,13 @@ class ImageConverter
     /// matrix method, and the metadata of the given OIIO::ImageSpec object.
     /// Use this method if you already have an image read from file to save
     /// on disk operations.
-    /// - parameter imageSpec:
+    /// @param imageSpec
     ///    An image spec obtained from OIIO::ImageInput or OIIO::ImageBuf.
-    /// - parameter hints:
+    /// @param hints
     ///    Conversion hints to be passed to OIIO when reading an image file.
     ///    The list can be pre- or post- updated with other hints, unrelated to
     ///    the rawtoaces conversion.
-    /// - returns
+    /// @result
     ///    `true` if configured successfully.
     bool
     configure( const OIIO::ImageSpec &imageSpec, OIIO::ParamValueList &hints );
@@ -192,85 +189,85 @@ class ImageConverter
 
     /// Apply the colour space conversion matrix (or matrices) to convert the
     /// image buffer from the raw camera colour space to ACES.
-    /// - parameter dst:
+    /// @param dst
     ///     Destination image buffer.
-    /// - parameter src:
+    /// @param src
     ///     Source image buffer, can be the same as `dst` for in-place
     ///     conversion.
-    /// - returns
+    /// @result
     ///    `true` if applied successfully.
     bool apply_matrix(
         OIIO::ImageBuf &dst, const OIIO::ImageBuf &src, OIIO::ROI roi = {} );
 
     /// Apply the headroom scale to image buffer.
-    /// - parameter dst:
+    /// @param dst
     ///     Destination image buffer.
-    /// - parameter src:
+    /// @param src
     ///     Source image buffer, can be the same as `dst` for in-place
     ///     conversion.
-    /// - returns
+    /// @result
     ///    `true` if applied successfully.
     bool apply_scale(
         OIIO::ImageBuf &dst, const OIIO::ImageBuf &src, OIIO::ROI roi = {} );
 
     /// Apply the cropping mode as specified in crop_mode.
-    /// - parameter dst:
+    /// @param dst
     ///     Destination image buffer.
-    /// - parameter src:
+    /// @param src
     ///     Source image buffer, can be the same as `dst` for in-place
     ///     conversion.
-    /// - returns
+    /// @result
     ///    `true` if applied successfully.
     bool apply_crop(
         OIIO::ImageBuf &dst, const OIIO::ImageBuf &src, OIIO::ROI roi = {} );
 
     /// Make output file path and check if it is writable.
-    /// - parameter path:
+    /// @param path
     ///     A reference to a variable containing the input file path. The output file path gets generated
     ///     in-place.
-    /// - parameter suffix:
+    /// @param suffix
     ///     A suffix to add to the file name.
-    /// - returns
+    /// @result
     ///    `true` if the file can be written, e.g. the output directory exists, or creating directories
     ///     is allowed; the file does not exist or overwriting is allowed.
     bool
     make_output_path( std::string &path, const std::string &suffix = "_aces" );
 
     /// Saves the image into ACES Container.
-    /// - parameter output_filename:
+    /// @param output_filename
     ///     Full path to the file to be saved.
-    /// - parameter buf:
+    /// @param buf
     ///     Image buffer to be saved.
-    /// - returns
+    /// @result
     ///    `true` if saved successfully.
     bool
     save_image( const std::string &output_filename, const OIIO::ImageBuf &buf );
 
     /// A convenience single-call method to process an image. This is equivalent to calling the following
     /// methods sequentially: `make_output_path`->`configure`->`apply_matrix`->
     /// `apply_scale`->`apply_crop`->`save`.
-    /// - parameter input_filename:
+    /// @param input_filename
     ///     Full path to the file to be converted.
-    /// - returns
+    /// @result
     ///    `true` if processed successfully.
     bool process_image( const std::string &input_filename );
 
     /// Get the solved white balance multipliers of the currently processed
     /// image. The multipliers become available after calling either of the
     /// two `configure` methods.
-    /// - returns a reference to the multipliers vector.
+    /// @result a reference to the multipliers vector.
     const std::vector<double> &get_WB_multipliers();
 
     /// Get the solved input transform matrix of the currently processed image.
     /// The multipliers become available after calling either of the two
     /// `configure` methods.
-    /// - returns a reference to the matrix.
+    /// @result a reference to the matrix.
     const std::vector<std::vector<double>> &get_IDT_matrix();
 
     /// Get the solved chromatic adaptation transform matrix of the currently
     /// processed image. The multipliers become available after calling either
     /// of the two `configure` methods.
-    /// - returns a reference to the matrix.
+    /// @result a reference to the matrix.
     const std::vector<std::vector<double>> &get_CAT_matrix();
 
 private:

include/rawtoaces/rawtoaces_core.h

@@ -28,95 +28,104 @@ static const std::vector<std::vector<double> > CAT_D65_to_ACES = {
 // clang-format on
 
 /// Calculate spectral power distribution of a daylight illuminant of given CCT
-/// - parameter cct: correlated colour temperature of the requested illuminant.
-/// - parameter spectrum: a reference to a `Spectrum` object to full with the
+/// @param cct correlated colour temperature of the requested illuminant.
+/// @param spectrum a reference to a `Spectrum` object to full with the
 /// calculated values.
 void calculate_daylight_SPD( const int &cct, Spectrum &spectrum );
 
 /// Calculate spectral power distribution of a blackbody illuminant of given CCT
-/// - parameter cct: correlated colour temperature of the requested illuminant.
-/// - parameter spectrum: a reference to a `Spectrum` object to full with the
+/// @param cct correlated colour temperature of the requested illuminant.
+/// @param spectrum a reference to a `Spectrum` object to full with the
 /// calculated values.
 void calculate_blackbody_SPD( const int &cct, Spectrum &spectrum );
 
 /// Solve an input transform using spectral sensitivity curves of a camera.
 class SpectralSolver
 {
 public:
-    SpectralSolver();
+    /// The camera spectral data. Can be either assigned directly, loaded
+    /// in-place place via `solver.camera.load()`, or found via
+    /// `solver.find_camera()`.
+    SpectralData camera;
+
+    /// The illuminant spectral data. Can be either assigned directly, loaded
+    /// in-place place via `solver.illuminant.load()`, or found via
+    /// `solver.find_illuminant()`.
+    SpectralData illuminant;
+
+    /// The observer spectral data. Can be either assigned directly, or loaded
+    /// in-place place via `solver.observer.load()`.
+    SpectralData observer;
+
+    /// The training set spectral data. Can be either assigned directly, or loaded
+    /// in-place place via `solver.training_data.load()`.
+    SpectralData training_data;
+
+    /// The constructor. Takes the database search path as an optional
+    /// parameter.
+    /// @param search_directories optional database search path.
+    SpectralSolver( const std::vector<std::string> &search_directories = {} );
+
+    /// A helper method collecting of spectral data files of a given type from
+    /// the database.
+    /// @param type data type of the files to search for.
+    /// @result a collection of files found in the database.
+    std::vector<std::string>
+    collect_data_files( const std::string &type ) const;
+
+    /// A helper method loading the spectral data for a file at the given path.
+    /// @param file_path the path to the file to load. If the path is relative,
+    /// all locations in the search path will be searched in.
+    /// @param out_data the `SpectralData` object to be filled with the loaded
+    /// data.
+    /// @result `true` is loaded successfully.
+    bool
+    load_spectral_data( const std::string &file_path, SpectralData &out_data );
 
     /// Load spectral sensitivity data for a camera.
-    /// - parameter path: a path to the data file
-    /// - parameter make: the camera make to verify the loaded data against.
-    /// - parameter model: the camera model to verify the loaded data against.
-    /// - returns `true` if loaded successfully.
-    bool load_camera(
-        const std::string &path,
-        const std::string &make,
-        const std::string &model );
-
-    /// Load spectral power distribution data for an illuminant.
-    /// If an illuminant type specified, try to find the matching data,
-    /// otherwise load all known illuminants.
-    /// - parameter paths: a set of data file paths to the data file
-    /// - parameter type: illuminant type to load.
-    /// - returns `true` if loaded successfully.
-    bool load_illuminant(
-        const std::vector<std::string> &paths, const std::string &type = "" );
-
-    /// Load spectral reflectivity data for a training set (a colour chart).
-    /// - parameter path: a path to the data file
-    /// - returns `true` if loaded successfully.
-    bool load_training_data( const std::string &path );
-
-    /// Load spectral sensitivity data for an observer
-    /// (colour matching functions).
-    /// - parameter path: a path to the data file
-    /// - returns `true` if loaded successfully.
-    bool load_observer( const std::string &path );
+    /// @param make the camera make to search for.
+    /// @param model the camera model to search for.
+    /// @result `true` if loaded successfully.
+    bool find_camera( const std::string &make, const std::string &model );
+
+    /// Find spectral power distribution data of an illuminant of the given
+    /// type.
+    /// @param type illuminant type. Can be one of the built-in types,
+    /// e.g. `d55`, `3200k`, or a custom illuminant stored in the database.
+    /// @result `true` if loaded successfully.
+    bool find_illuminant( const std::string &type );
 
     /// Find the illuminant best matching the given white-balancing multipliers.
-    /// See `get_best_illuminant()` to access the result.
-    /// - parameter wb_multipliers: white-balancing multipliers to match.
-    /// - parameter highlight: the highlight recovery mode, used for
-    /// normalisation.
-    void find_best_illuminant(
-        const std::vector<double> &wb_multipliers, int highlight );
-
-    /// Select an illuminant of a given type.
-    /// See `get_best_illuminant()` to access the result.
-    /// - parameter type: illuminant type to select.
-    /// - parameter highlight: the highlight recovery mode, used for
-    /// normalisation.
-    void select_illuminant( const std::string &type, int highlight );
-
-    /// Calculate an input transform matrix.
-    /// See `get_IDT_matrix()` to access the result.
-    /// - returns `true` if calculated successfully.
+    /// @param wb_multipliers white-balancing multipliers to match.
+    /// @result `true` if loaded successfully.
+    bool find_illuminant( const std::vector<double> &wb_multipliers );
+
+    /// Calculate the white-balance multipliers for the given configuration.
+    /// The `camera`, and `illuminant` data have to be configured prior to this
+    /// call. See `get_WB_multipliers()` to access the result.
+    /// @result `true` if calculated successfully.
+    bool calculate_WB();
+
+    /// Calculate an input transform matrix. The `camera`,  `illuminant`,
+    /// `observer` and `training_data` have to be configured prior to this
+    /// call. See `get_IDT_matrix()` to access the result.
+    /// @result `true` if calculated successfully.
     bool calculate_IDT_matrix();
 
-    /// Get the illuminant configured using `find_best_illuminant()` or
-    /// `select_illuminant()`.
-    /// - returns a reference to the illuminant.
-    const SpectralData &get_best_illuminant() const;
-
     /// Get the matrix calculated using `calculate_IDT_matrix()`.
-    /// - returns a reference to the matrix.
+    /// @result a reference to the matrix.
     const std::vector<std::vector<double>> &get_IDT_matrix() const;
 
     /// Get the white-balance multipliers calculated using
     /// `find_best_illuminant()` or `select_illuminant()`.
-    /// - returns a reference to the multipliers.
+    /// @result a reference to the multipliers.
     const std::vector<double> &get_WB_multipliers() const;
 
     int verbosity = 0;
 
 private:
-    SpectralData              _camera;
-    SpectralData              _best_illuminant;
-    SpectralData              _observer;
-    SpectralData              _training_data;
-    std::vector<SpectralData> _illuminants;
+    std::vector<std::string>  _search_directories;
+    std::vector<SpectralData> _all_illuminants;
 
     std::vector<double>              _WB_multipliers;
     std::vector<std::vector<double>> _IDT_matrix;
@@ -142,17 +151,17 @@ class MetadataSolver
 {
 public:
     /// Initialise the solver using DNG metadata.
-    /// - parameter metadata: DNG metadata
+    /// @param metadata DNG metadata
     MetadataSolver( const core::Metadata &metadata );
 
     /// Calculate an input transform matrix.
-    /// - returns: calculated matrix
+    /// @result calculated matrix
     std::vector<std::vector<double>> calculate_IDT_matrix();
 
     /// Calculate a chromatic adaptation transform matrix. Strictly speaking,
     /// this matrix is not required for image processing, as it is embedded in
     /// the IDT, see `calculate_IDT_matrix`.
-    /// - returns: calculated matrix
+    /// @result calculated matrix
     std::vector<std::vector<double>> calculate_CAT_matrix();
 
 private: