11d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Ceres Solver - A fast non-linear least squares minimizer
21d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * Copyright 2013 Google Inc. All rights reserved.
31d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * http://code.google.com/p/ceres-solver/
41d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
51d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * Redistribution and use in source and binary forms, with or without
61d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * modification, are permitted provided that the following conditions are met:
71d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
81d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * - Redistributions of source code must retain the above copyright notice,
91d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *   this list of conditions and the following disclaimer.
101d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * - Redistributions in binary form must reproduce the above copyright notice,
111d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *   this list of conditions and the following disclaimer in the documentation
121d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *   and/or other materials provided with the distribution.
131d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * - Neither the name of Google Inc. nor the names of its contributors may be
141d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *   used to endorse or promote products derived from this software without
151d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *   specific prior written permission.
161d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
171d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
181d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
191d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
201d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
211d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
221d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
231d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
241d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
251d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
261d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
271d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * POSSIBILITY OF SUCH DAMAGE.
281d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
291d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * Author: mierle@gmail.com (Keir Mierle)
301d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
311d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * A minimal C API for Ceres. Not all functionality is included. This API is
321d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * not intended for clients of Ceres, but is instead intended for easing the
331d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * process of binding Ceres to other languages.
341d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
351d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * Currently this is a work in progress.
361d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling */
371d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
381d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#ifndef CERES_PUBLIC_C_API_H_
391d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#define CERES_PUBLIC_C_API_H_
401d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
411d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#ifdef __cplusplus
421d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingextern "C" {
431d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#endif
441d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
451d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Init the Ceres private data. Must be called before anything else. */
461d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid ceres_init();
471d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
481d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Equivalent to CostFunction::Evaluate() in the C++ API.
491d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
501d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * The user may keep private information inside the opaque user_data object.
511d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * The pointer here is the same one passed in the ceres_add_residual_block().
521d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling */
531d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef int (*ceres_cost_function_t)(void* user_data,
541d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling                                     double** parameters,
551d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling                                     double* residuals,
561d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling                                     double** jacobians);
571d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
581d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Equivalent to LossFunction::Evaluate() from the C++ API. */
591d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef void (*ceres_loss_function_t)(void* user_data,
601d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling                                      double squared_norm,
611d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling                                      double out[3]);
621d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
631d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Create callback data for Ceres' stock loss functions.
641d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
651d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * Ceres has several loss functions available by default, and these functions
661d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * expose those to the C API. To use the stock loss functions, call
671d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_create_*_loss_data(), which internally creates an instance of one of
681d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * the stock loss functions (for example ceres::CauchyLoss), and pass the
691d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * returned "loss_function_data" along with the ceres_stock_loss_function to
701d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_add_residual_block().
711d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
721d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * For example:
731d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
741d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *   void* cauchy_loss_function_data =
751d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       ceres_create_cauchy_loss_function_data(1.2, 0.0);
761d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *   ceres_problem_add_residual_block(
771d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       problem,
781d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       my_cost_function,
791d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       my_cost_function_data,
801d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       ceres_stock_loss_function,
811d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       cauchy_loss_function_data,
821d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       1,
831d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       2,
841d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       parameter_sizes,
851d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *       parameter_pointers);
861d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *    ...
871d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *    ceres_free_stock_loss_function_data(cauchy_loss_function_data);
881d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling *
891d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * See loss_function.h for the details of each loss function.
901d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling */
911d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid* ceres_create_huber_loss_function_data(double a);
921d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid* ceres_create_softl1_loss_function_data(double a);
931d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid* ceres_create_cauchy_loss_function_data(double a);
941d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid* ceres_create_arctan_loss_function_data(double a);
951d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid* ceres_create_tolerant_loss_function_data(double a, double b);
961d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
971d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Free the given stock loss function data. */
981d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid ceres_free_stock_loss_function_data(void* loss_function_data);
991d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1001d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* This is an implementation of ceres_loss_function_t contained within Ceres
1011d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * itself, intended as a way to access the various stock Ceres loss functions
1021d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * from the C API. This should be passed to ceres_add_residual() below, in
1031d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * combination with a user_data pointer generated by
1041d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_create_stock_loss_function() above. */
1051d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid ceres_stock_loss_function(void* user_data,
1061d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling                               double squared_norm,
1071d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling                               double out[3]);
1081d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1091d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Equivalent to Problem from the C++ API. */
1101d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingstruct ceres_problem_s;
1111d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef struct ceres_problem_s ceres_problem_t;
1121d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1131d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingstruct ceres_residual_block_id_s;
1141d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef struct ceres_residual_block_id_s ceres_residual_block_id_t;
1151d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1161d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Create and destroy a problem */
1171d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* TODO(keir): Add options for the problem. */
1181d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingceres_problem_t* ceres_create_problem();
1191d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid ceres_free_problem(ceres_problem_t* problem);
1201d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1211d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Add a residual block. */
1221d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingceres_residual_block_id_t* ceres_problem_add_residual_block(
1231d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    ceres_problem_t* problem,
1241d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    ceres_cost_function_t cost_function,
1251d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    void* cost_function_data,
1261d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    ceres_loss_function_t loss_function,
1271d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    void* loss_function_data,
1281d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    int num_residuals,
1291d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    int num_parameter_blocks,
1301d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    int* parameter_block_sizes,
1311d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling    double** parameters);
1321d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1331d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingvoid ceres_solve(ceres_problem_t* problem);
1341d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1351d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* TODO(keir): Figure out a way to pass a config in. */
1361d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1371d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#ifdef __cplusplus
1381d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling}
1391d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#endif
1401d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling
1411d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#endif  /* CERES_PUBLIC_C_API_H_ */
142