1 /* Ceres Solver - A fast non-linear least squares minimizer 2 * Copyright 2013 Google Inc. All rights reserved. 3 * http://code.google.com/p/ceres-solver/ 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 (at) 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_ */ 147
