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 4179397c21138f54fcff6ec067b44b847f1f7e0e98Carlos Hernandez#include "ceres/internal/port.h" 4279397c21138f54fcff6ec067b44b847f1f7e0e98Carlos Hernandez#include "ceres/internal/disable_warnings.h" 4379397c21138f54fcff6ec067b44b847f1f7e0e98Carlos Hernandez 441d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#ifdef __cplusplus 451d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingextern "C" { 461d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#endif 471d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 481d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Init the Ceres private data. Must be called before anything else. */ 4979397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void ceres_init(); 501d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 511d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Equivalent to CostFunction::Evaluate() in the C++ API. 521d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * 531d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * The user may keep private information inside the opaque user_data object. 541d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * The pointer here is the same one passed in the ceres_add_residual_block(). 551d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling */ 561d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef int (*ceres_cost_function_t)(void* user_data, 571d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double** parameters, 581d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double* residuals, 591d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double** jacobians); 601d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 611d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Equivalent to LossFunction::Evaluate() from the C++ API. */ 621d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef void (*ceres_loss_function_t)(void* user_data, 631d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double squared_norm, 641d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double out[3]); 651d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 661d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Create callback data for Ceres' stock loss functions. 671d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * 681d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * Ceres has several loss functions available by default, and these functions 691d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * expose those to the C API. To use the stock loss functions, call 701d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_create_*_loss_data(), which internally creates an instance of one of 711d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * the stock loss functions (for example ceres::CauchyLoss), and pass the 721d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * returned "loss_function_data" along with the ceres_stock_loss_function to 731d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_add_residual_block(). 741d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * 751d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * For example: 761d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * 771d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * void* cauchy_loss_function_data = 781d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_create_cauchy_loss_function_data(1.2, 0.0); 791d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_problem_add_residual_block( 801d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * problem, 811d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * my_cost_function, 821d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * my_cost_function_data, 831d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_stock_loss_function, 841d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * cauchy_loss_function_data, 851d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * 1, 861d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * 2, 871d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * parameter_sizes, 881d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * parameter_pointers); 891d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ... 901d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_free_stock_loss_function_data(cauchy_loss_function_data); 911d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * 921d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * See loss_function.h for the details of each loss function. 931d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling */ 9479397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void* ceres_create_huber_loss_function_data(double a); 9579397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void* ceres_create_softl1_loss_function_data(double a); 9679397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void* ceres_create_cauchy_loss_function_data(double a); 9779397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void* ceres_create_arctan_loss_function_data(double a); 9879397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void* ceres_create_tolerant_loss_function_data(double a, double b); 991d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1001d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Free the given stock loss function data. */ 10179397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void ceres_free_stock_loss_function_data(void* loss_function_data); 1021d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1031d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* This is an implementation of ceres_loss_function_t contained within Ceres 1041d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * itself, intended as a way to access the various stock Ceres loss functions 1051d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * from the C API. This should be passed to ceres_add_residual() below, in 1061d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * combination with a user_data pointer generated by 1071d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling * ceres_create_stock_loss_function() above. */ 10879397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void ceres_stock_loss_function(void* user_data, 10979397c21138f54fcff6ec067b44b847f1f7e0e98Carlos Hernandez double squared_norm, 11079397c21138f54fcff6ec067b44b847f1f7e0e98Carlos Hernandez double out[3]); 1111d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1121d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Equivalent to Problem from the C++ API. */ 1131d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingstruct ceres_problem_s; 1141d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef struct ceres_problem_s ceres_problem_t; 1151d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1161d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingstruct ceres_residual_block_id_s; 1171d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberlingtypedef struct ceres_residual_block_id_s ceres_residual_block_id_t; 1181d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1191d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Create and destroy a problem */ 1201d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* TODO(keir): Add options for the problem. */ 12179397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT ceres_problem_t* ceres_create_problem(); 12279397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void ceres_free_problem(ceres_problem_t* problem); 1231d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1241d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* Add a residual block. */ 12579397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT ceres_residual_block_id_t* ceres_problem_add_residual_block( 1261d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling ceres_problem_t* problem, 1271d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling ceres_cost_function_t cost_function, 1281d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling void* cost_function_data, 1291d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling ceres_loss_function_t loss_function, 1301d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling void* loss_function_data, 1311d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling int num_residuals, 1321d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling int num_parameter_blocks, 1331d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling int* parameter_block_sizes, 1341d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double** parameters); 1351d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 13679397c21138f54fcff6ec067b44b847f1f7e0e98Carlos HernandezCERES_EXPORT void ceres_solve(ceres_problem_t* problem); 1371d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1381d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling/* TODO(keir): Figure out a way to pass a config in. */ 1391d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1401d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#ifdef __cplusplus 1411d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling} 1421d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#endif 1431d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 14479397c21138f54fcff6ec067b44b847f1f7e0e98Carlos Hernandez#include "ceres/internal/reenable_warnings.h" 14579397c21138f54fcff6ec067b44b847f1f7e0e98Carlos Hernandez 1461d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#endif /* CERES_PUBLIC_C_API_H_ */ 147