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@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
45extern "C" {
46#endif
47
48/* Init the Ceres private data. Must be called before anything else. */
49CERES_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 */
56typedef 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. */
62typedef 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 */
94CERES_EXPORT void* ceres_create_huber_loss_function_data(double a);
95CERES_EXPORT void* ceres_create_softl1_loss_function_data(double a);
96CERES_EXPORT void* ceres_create_cauchy_loss_function_data(double a);
97CERES_EXPORT void* ceres_create_arctan_loss_function_data(double a);
98CERES_EXPORT void* ceres_create_tolerant_loss_function_data(double a, double b);
99
100/* Free the given stock loss function data. */
101CERES_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. */
108CERES_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. */
113struct ceres_problem_s;
114typedef struct ceres_problem_s ceres_problem_t;
115
116struct ceres_residual_block_id_s;
117typedef 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. */
121CERES_EXPORT ceres_problem_t* ceres_create_problem();
122CERES_EXPORT void ceres_free_problem(ceres_problem_t* problem);
123
124/* Add a residual block. */
125CERES_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
136CERES_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