include/ceres/c_api.h

   1 /* Ceres Solver - A fast non-linear least squares minimizer
   2  * Copyright 2015 Google Inc. All rights reserved.
   3  * http://ceres-solver.org/
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are met:
   7  *
   8  * - Redistributions of source code must retain the above copyright notice,
   9  *   this list of conditions and the following disclaimer.
  10  * - Redistributions in binary form must reproduce the above copyright notice,
  11  *   this list of conditions and the following disclaimer in the documentation
  12  *   and/or other materials provided with the distribution.
  13  * - Neither the name of Google Inc. nor the names of its contributors may be
  14  *   used to endorse or promote products derived from this software without
  15  *   specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  21  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27  * POSSIBILITY OF SUCH DAMAGE.
  28  *
  29  * Author: mierle@gmail.com (Keir Mierle)
  30  *
  31  * A minimal C API for Ceres. Not all functionality is included. This API is
  32  * not intended for clients of Ceres, but is instead intended for easing the
  33  * process of binding Ceres to other languages.
  34  *
  35  * Currently this is a work in progress.
  36  */
  37
  38 #ifndef CERES_PUBLIC_C_API_H_
  39 #define CERES_PUBLIC_C_API_H_
  40
  41 #include "ceres/internal/port.h"
  42 #include "ceres/internal/disable_warnings.h"
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 /* Init the Ceres private data. Must be called before anything else. */
  49 CERES_EXPORT void ceres_init();
  50
  51 /* Equivalent to CostFunction::Evaluate() in the C++ API.
  52  *
  53  * The user may keep private information inside the opaque user_data object.
  54  * The pointer here is the same one passed in the ceres_add_residual_block().
  55  */
  56 typedef int (*ceres_cost_function_t)(void* user_data,
  57                                      double** parameters,
  58                                      double* residuals,
  59                                      double** jacobians);
  60
  61 /* Equivalent to LossFunction::Evaluate() from the C++ API. */
  62 typedef void (*ceres_loss_function_t)(void* user_data,
  63                                       double squared_norm,
  64                                       double out[3]);
  65
  66 /* Create callback data for Ceres' stock loss functions.
  67  *
  68  * Ceres has several loss functions available by default, and these functions
  69  * expose those to the C API. To use the stock loss functions, call
  70  * ceres_create_*_loss_data(), which internally creates an instance of one of
  71  * the stock loss functions (for example ceres::CauchyLoss), and pass the
  72  * returned "loss_function_data" along with the ceres_stock_loss_function to
  73  * ceres_add_residual_block().
  74  *
  75  * For example:
  76  *
  77  *   void* cauchy_loss_function_data =
  78  *       ceres_create_cauchy_loss_function_data(1.2, 0.0);
  79  *   ceres_problem_add_residual_block(
  80  *       problem,
  81  *       my_cost_function,
  82  *       my_cost_function_data,
  83  *       ceres_stock_loss_function,
  84  *       cauchy_loss_function_data,
  85  *       1,
  86  *       2,
  87  *       parameter_sizes,
  88  *       parameter_pointers);
  89  *    ...
  90  *    ceres_free_stock_loss_function_data(cauchy_loss_function_data);
  91  *
  92  * See loss_function.h for the details of each loss function.
  93  */
  94 CERES_EXPORT void* ceres_create_huber_loss_function_data(double a);
  95 CERES_EXPORT void* ceres_create_softl1_loss_function_data(double a);
  96 CERES_EXPORT void* ceres_create_cauchy_loss_function_data(double a);
  97 CERES_EXPORT void* ceres_create_arctan_loss_function_data(double a);
  98 CERES_EXPORT void* ceres_create_tolerant_loss_function_data(double a, double b);
  99
 100 /* Free the given stock loss function data. */
 101 CERES_EXPORT void ceres_free_stock_loss_function_data(void* loss_function_data);
 102
 103 /* This is an implementation of ceres_loss_function_t contained within Ceres
 104  * itself, intended as a way to access the various stock Ceres loss functions
 105  * from the C API. This should be passed to ceres_add_residual() below, in
 106  * combination with a user_data pointer generated by
 107  * ceres_create_stock_loss_function() above. */
 108 CERES_EXPORT void ceres_stock_loss_function(void* user_data,
 109                                             double squared_norm,
 110                                             double out[3]);
 111
 112 /* Equivalent to Problem from the C++ API. */
 113 struct ceres_problem_s;
 114 typedef struct ceres_problem_s ceres_problem_t;
 115
 116 struct ceres_residual_block_id_s;
 117 typedef struct ceres_residual_block_id_s ceres_residual_block_id_t;
 118
 119 /* Create and destroy a problem */
 120 /* TODO(keir): Add options for the problem. */
 121 CERES_EXPORT ceres_problem_t* ceres_create_problem();
 122 CERES_EXPORT void ceres_free_problem(ceres_problem_t* problem);
 123
 124 /* Add a residual block. */
 125 CERES_EXPORT ceres_residual_block_id_t* ceres_problem_add_residual_block(
 126     ceres_problem_t* problem,
 127     ceres_cost_function_t cost_function,
 128     void* cost_function_data,
 129     ceres_loss_function_t loss_function,
 130     void* loss_function_data,
 131     int num_residuals,
 132     int num_parameter_blocks,
 133     int* parameter_block_sizes,
 134     double** parameters);
 135
 136 CERES_EXPORT void ceres_solve(ceres_problem_t* problem);
 137
 138 /* TODO(keir): Figure out a way to pass a config in. */
 139
 140 #ifdef __cplusplus
 141 }
 142 #endif
 143
 144 #include "ceres/internal/reenable_warnings.h"
 145
 146 #endif  /* CERES_PUBLIC_C_API_H_ */