1// Ceres Solver - A fast non-linear least squares minimizer
2// Copyright 2010, 2011, 2012 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: wjr@google.com (William Rucklidge)
30//
31// This file contains a cost function that can apply a transformation to
32// each residual value before they are square-summed.
33
34#ifndef CERES_PUBLIC_CONDITIONED_COST_FUNCTION_H_
35#define CERES_PUBLIC_CONDITIONED_COST_FUNCTION_H_
36
37#include <vector>
38
39#include "ceres/cost_function.h"
40#include "ceres/internal/scoped_ptr.h"
41#include "ceres/types.h"
42
43namespace ceres {
44
45// This class allows you to apply different conditioning to the residual
46// values of a wrapped cost function. An example where this is useful is
47// where you have an existing cost function that produces N values, but you
48// want the total cost to be something other than just the sum of these
49// squared values - maybe you want to apply a different scaling to some
50// values, to change their contribution to the cost.
51//
52// Usage:
53//
54//   // my_cost_function produces N residuals
55//   CostFunction* my_cost_function = ...
56//   CHECK_EQ(N, my_cost_function->num_residuals());
57//   vector<CostFunction*> conditioners;
58//
59//   // Make N 1x1 cost functions (1 parameter, 1 residual)
60//   CostFunction* f_1 = ...
61//   conditioners.push_back(f_1);
62//   ...
63//   CostFunction* f_N = ...
64//   conditioners.push_back(f_N);
65//   ConditionedCostFunction* ccf =
66//     new ConditionedCostFunction(my_cost_function, conditioners);
67//
68// Now ccf's residual i (i=0..N-1) will be passed though the i'th conditioner.
69//
70//   ccf_residual[i] = f_i(my_cost_function_residual[i])
71//
72// and the Jacobian will be affected appropriately.
73class ConditionedCostFunction : public CostFunction {
74 public:
75  // Builds a cost function based on a wrapped cost function, and a
76  // per-residual conditioner. Takes ownership of all of the wrapped cost
77  // functions, or not, depending on the ownership parameter. Conditioners
78  // may be NULL, in which case the corresponding residual is not modified.
79  ConditionedCostFunction(CostFunction* wrapped_cost_function,
80                          const vector<CostFunction*>& conditioners,
81                          Ownership ownership);
82  virtual ~ConditionedCostFunction();
83
84  virtual bool Evaluate(double const* const* parameters,
85                        double* residuals,
86                        double** jacobians) const;
87
88 private:
89  internal::scoped_ptr<CostFunction> wrapped_cost_function_;
90  vector<CostFunction*> conditioners_;
91  Ownership ownership_;
92};
93
94}  // namespace ceres
95
96
97#endif  // CERES_PUBLIC_CONDITIONED_COST_FUNCTION_H_
98