/* Copyright (c) 2016 - 2021, the adamantine authors.
 *
 * This file is subject to the Modified BSD License and may not be distributed
 * without copyright and license information. Please refer to the file LICENSE
 * for the text and further information on this license.
 */

#ifndef ADAMANTINE_HH
#define ADAMANTINE_HH

#include <Geometry.hh>
#include <PostProcessor.hh>
#include <ThermalPhysics.hh>
#include <Timer.hh>
#include <ensemble_management.hh>
#include <material_deposition.hh>
#include <utils.hh>

#include <deal.II/base/mpi.h>
#include <deal.II/distributed/solution_transfer.h>
#include <deal.II/grid/filtered_iterator.h>
#include <deal.II/grid/grid_refinement.h>
#include <deal.II/numerics/error_estimator.h>

#include <boost/program_options.hpp>
#include <boost/property_tree/info_parser.hpp>
#include <boost/property_tree/ptree.hpp>

#ifdef ADAMANTINE_WITH_CALIPER
#include <caliper/cali.h>
#endif

#include <cmath>
#include <iostream>

template <int dim, typename MemorySpaceType,
          std::enable_if_t<
              std::is_same<MemorySpaceType, dealii::MemorySpace::Host>::value,
              int> = 0>
void output_pvtu(
    adamantine::PostProcessor<dim> &post_processor, unsigned int cycle,
    unsigned int n_time_step, double time,
    dealii::AffineConstraints<double> const &affine_constraints,
    dealii::LinearAlgebra::distributed::Vector<double, MemorySpaceType>
        &solution,
    std::vector<adamantine::Timer> &timers)
{
#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_FUNCTION;
#endif
  timers[adamantine::output].start();
  affine_constraints.distribute(solution);
  post_processor.output_pvtu(cycle, n_time_step, time, solution);
  timers[adamantine::output].stop();
}

#ifdef ADAMANTINE_HAVE_CUDA
template <int dim, typename MemorySpaceType,
          std::enable_if_t<
              std::is_same<MemorySpaceType, dealii::MemorySpace::CUDA>::value,
              int> = 0>
void output_pvtu(
    adamantine::PostProcessor<dim> &post_processor, unsigned int cycle,
    unsigned int n_time_step, double time,
    dealii::AffineConstraints<double> const &affine_constraints,
    dealii::LinearAlgebra::distributed::Vector<double, MemorySpaceType>
        &solution,
    std::vector<adamantine::Timer> &timers)
{
#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_FUNCTION;
#endif
  timers[adamantine::output].start();
  dealii::LinearAlgebra::distributed::Vector<double, dealii::MemorySpace::Host>
      solution_host(solution.get_partitioner());
  solution_host.import(solution, dealii::VectorOperation::insert);
  affine_constraints.distribute(solution_host);
  post_processor.output_pvtu(cycle, n_time_step, time, solution_host);
  timers[adamantine::output].stop();
}
#endif

template <int dim, typename MemorySpaceType,
          std::enable_if_t<
              std::is_same<MemorySpaceType, dealii::MemorySpace::Host>::value,
              int> = 0>
dealii::Vector<float> estimate_error(
    dealii::parallel::distributed::Triangulation<dim> const &triangulation,
    dealii::DoFHandler<dim> const &dof_handler, int fe_degree,
    dealii::LA::distributed::Vector<double, MemorySpaceType> const &solution)
{
  dealii::Vector<float> estimated_error_per_cell(
      triangulation.n_active_cells());
  dealii::KellyErrorEstimator<dim>::estimate(
      dof_handler, dealii::QGauss<dim - 1>(fe_degree + 1),
      std::map<dealii::types::boundary_id,
               const dealii::Function<dim, double> *>(),
      solution, estimated_error_per_cell, dealii::ComponentMask(), nullptr, 0,
      triangulation.locally_owned_subdomain());

  return estimated_error_per_cell;
}

#ifdef ADAMANTINE_HAVE_CUDA
template <int dim, typename MemorySpaceType,
          std::enable_if_t<
              std::is_same<MemorySpaceType, dealii::MemorySpace::CUDA>::value,
              int> = 0>
dealii::Vector<float> estimate_error(
    dealii::parallel::distributed::Triangulation<dim> const &triangulation,
    dealii::DoFHandler<dim> const &dof_handler, int fe_degree,
    dealii::LA::distributed::Vector<double, MemorySpaceType> const &solution)
{
  dealii::LA::distributed::Vector<double, dealii::MemorySpace::Host>
      solution_host(solution.get_partitioner());
  solution_host.import(solution, dealii::VectorOperation::insert);
  dealii::Vector<float> estimated_error_per_cell(
      triangulation.n_active_cells());
  dealii::KellyErrorEstimator<dim>::estimate(
      dof_handler, dealii::QGauss<dim - 1>(fe_degree + 1),
      std::map<dealii::types::boundary_id,
               const dealii::Function<dim, double> *>(),
      solution_host, estimated_error_per_cell, dealii::ComponentMask(), nullptr,
      0, triangulation.locally_owned_subdomain());

  return estimated_error_per_cell;
}
#endif

// inlining this function so we can have in the header
inline void initialize_timers(MPI_Comm const &communicator,
                              std::vector<adamantine::Timer> &timers)
{
  timers.push_back(adamantine::Timer(communicator, "Main"));
  timers.push_back(adamantine::Timer(communicator, "Refinement"));
  timers.push_back(adamantine::Timer(communicator, "Add Material, Search"));
  timers.push_back(adamantine::Timer(communicator, "Add Material, Activate"));
  timers.push_back(adamantine::Timer(communicator, "Evolve One Time Step"));
  timers.push_back(adamantine::Timer(
      communicator, "Evolve One Time Step: evaluate_thermal_physics"));
  timers.push_back(adamantine::Timer(
      communicator, "Evolve One Time Step: id_minus_tau_J_inverse"));
  timers.push_back(adamantine::Timer(
      communicator, "Evolve One Time Step: evaluate_material_properties"));
  timers.push_back(adamantine::Timer(communicator, "Output"));
}

template <int dim, int fe_degree, typename MemorySpaceType,
          typename QuadratureType>
std::vector<std::shared_ptr<adamantine::HeatSource<dim>>> &initialize(
    MPI_Comm const &communicator, boost::property_tree::ptree const &database,
    adamantine::Geometry<dim> &geometry,
    std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> &thermal_physics)
{
  thermal_physics.reset(
      new adamantine::ThermalPhysics<dim, fe_degree, MemorySpaceType,
                                     QuadratureType>(communicator, database,
                                                     geometry));
  return static_cast<adamantine::ThermalPhysics<dim, fe_degree, MemorySpaceType,
                                                QuadratureType> *>(
             thermal_physics.get())
      ->get_heat_sources();
}

template <int dim, int fe_degree, typename MemorySpaceType>
std::vector<std::shared_ptr<adamantine::HeatSource<dim>>> &
initialize_quadrature(
    std::string const &quadrature_type, MPI_Comm const &communicator,
    boost::property_tree::ptree const &database,
    adamantine::Geometry<dim> &geometry,
    std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> &thermal_physics)
{
  if (quadrature_type.compare("gauss") == 0)
    return initialize<dim, fe_degree, MemorySpaceType, dealii::QGauss<1>>(
        communicator, database, geometry, thermal_physics);
  else
  {
    adamantine::ASSERT_THROW(quadrature_type.compare("lobatto") == 0,
                             "quadrature should be Gauss or Lobatto.");
    return initialize<dim, fe_degree, MemorySpaceType,
                      dealii::QGaussLobatto<1>>(communicator, database,
                                                geometry, thermal_physics);
  }
}

template <int dim, typename MemorySpaceType>
std::vector<std::shared_ptr<adamantine::HeatSource<dim>>> &
initialize_thermal_physics(
    unsigned int fe_degree, std::string const &quadrature_type,
    MPI_Comm const &communicator, boost::property_tree::ptree const &database,
    adamantine::Geometry<dim> &geometry,
    std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> &thermal_physics)
{
  switch (fe_degree)
  {
  case 1:
  {
    return initialize_quadrature<dim, 1, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 2:
  {
    return initialize_quadrature<dim, 2, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 3:
  {
    return initialize_quadrature<dim, 3, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 4:
  {
    return initialize_quadrature<dim, 4, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 5:
  {
    return initialize_quadrature<dim, 5, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 6:
  {
    return initialize_quadrature<dim, 6, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 7:
  {
    return initialize_quadrature<dim, 7, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 8:
  {
    return initialize_quadrature<dim, 8, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  case 9:
  {
    return initialize_quadrature<dim, 9, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  default:
  {
    adamantine::ASSERT_THROW(fe_degree == 10,
                             "fe_degree should be between 1 and 10.");
    return initialize_quadrature<dim, 10, MemorySpaceType>(
        quadrature_type, communicator, database, geometry, thermal_physics);
  }
  }
}

template <int dim, typename MemorySpaceType,
          std::enable_if_t<
              std::is_same<MemorySpaceType, dealii::MemorySpace::Host>::value,
              int> = 0>
void refine_and_transfer(
    std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> &thermal_physics,
    dealii::DoFHandler<dim> &dof_handler,
    dealii::LA::distributed::Vector<double, MemorySpaceType> &solution)
{
  dealii::parallel::distributed::Triangulation<dim> &triangulation =
      dynamic_cast<dealii::parallel::distributed::Triangulation<dim> &>(
          const_cast<dealii::Triangulation<dim> &>(
              dof_handler.get_triangulation()));

  std::shared_ptr<adamantine::MaterialProperty<dim>> material_property =
      thermal_physics->get_material_property();

  dealii::parallel::distributed::SolutionTransfer<
      dim, dealii::LA::distributed::Vector<double, MemorySpaceType>>
      solution_transfer(dof_handler);
  std::vector<dealii::parallel::distributed::SolutionTransfer<
      dim, dealii::LA::distributed::Vector<double, MemorySpaceType>>>
      material_state(
          static_cast<unsigned int>(adamantine::MaterialState::SIZE),
          dealii::parallel::distributed::SolutionTransfer<
              dim, dealii::LA::distributed::Vector<double, MemorySpaceType>>(
              material_property->get_dof_handler()));

  // We need to update the ghost values before we can do the interpolation on
  // the new mesh.
  solution.update_ghost_values();

  // Prepare the Triangulation and the diffent SolutionTransfers for refinement
  triangulation.prepare_coarsening_and_refinement();
  solution_transfer.prepare_for_coarsening_and_refinement(solution);
  for (unsigned int i = 0;
       i < static_cast<unsigned int>(adamantine::MaterialState::SIZE); ++i)
    material_state[i].prepare_for_coarsening_and_refinement(
        material_property->get_state()[i]);

  // Execute the refinement
  triangulation.execute_coarsening_and_refinement();

  // Update the AffineConstraints and resize the solution
  thermal_physics->setup_dofs();
  thermal_physics->initialize_dof_vector(solution);

  // Update MaterialProperty DoFHandler and resize the state vectors
  material_property->reinit_dofs();

  // Interpolate the solution and the state onto the new mesh
  solution_transfer.interpolate(solution);
  for (unsigned int i = 0;
       i < static_cast<unsigned int>(adamantine::MaterialState::SIZE); ++i)
    material_state[i].interpolate(material_property->get_state()[i]);

#if ADAMANTINE_DEBUG
  // Check that we are not losing material
  std::array<dealii::LA::distributed::Vector<double, dealii::MemorySpace::Host>,
             static_cast<unsigned int>(adamantine::MaterialState::SIZE)>
      state = material_property->get_state();
  unsigned int const local_size = state[0].locally_owned_size();
  unsigned int constexpr n_material_states =
      static_cast<unsigned int>(adamantine::MaterialState::SIZE);
  for (unsigned int i = 0; i < local_size; ++i)
  {
    double material_ratio = 0.;
    for (unsigned int j = 0; j < n_material_states; ++j)
      material_ratio += state[j].local_element(i);
    adamantine::ASSERT(std::abs(material_ratio - 1.) < 1e-14,
                       "Material is lost.");
  }
#endif
}

#ifdef ADAMANTINE_HAVE_CUDA
template <int dim, typename MemorySpaceType,
          std::enable_if_t<
              std::is_same<MemorySpaceType, dealii::MemorySpace::CUDA>::value,
              int> = 0>
void refine_and_transfer(
    std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> &thermal_physics,
    dealii::DoFHandler<dim> &dof_handler,
    dealii::LA::distributed::Vector<double, MemorySpaceType> &solution)
{
  dealii::parallel::distributed::Triangulation<dim> &triangulation =
      dynamic_cast<dealii::parallel::distributed::Triangulation<dim> &>(
          const_cast<dealii::Triangulation<dim> &>(
              dof_handler.get_triangulation()));

  // Update the material state from the ThermalOperator to MaterialProperty
  // because, for now, we need to use state from MaterialProperty to perform the
  // transfer to the refined mesh.
  thermal_physics->set_state_to_material_properties();
  std::shared_ptr<adamantine::MaterialProperty<dim>> material_property =
      thermal_physics->get_material_property();

  dealii::parallel::distributed::SolutionTransfer<
      dim, dealii::LA::distributed::Vector<double, dealii::MemorySpace::Host>>
      solution_transfer(dof_handler);
  std::vector<dealii::parallel::distributed::SolutionTransfer<
      dim, dealii::LA::distributed::Vector<double, dealii::MemorySpace::Host>>>
      material_state(
          static_cast<unsigned int>(adamantine::MaterialState::SIZE),
          dealii::parallel::distributed::SolutionTransfer<
              dim, dealii::LA::distributed::Vector<double,
                                                   dealii::MemorySpace::Host>>(
              material_property->get_dof_handler()));

  // We need to update the ghost values before we can do the interpolation on
  // the new mesh.
  solution.update_ghost_values();

  // Prepare the Triangulation and the diffent SolutionTransfers for refinement
  triangulation.prepare_coarsening_and_refinement();
  dealii::LA::distributed::Vector<double, dealii::MemorySpace::Host>
      solution_host(solution.get_partitioner());
  solution_host.import(solution, dealii::VectorOperation::insert);
  solution_transfer.prepare_for_coarsening_and_refinement(solution_host);
  for (unsigned int i = 0;
       i < static_cast<unsigned int>(adamantine::MaterialState::SIZE); ++i)
    material_state[i].prepare_for_coarsening_and_refinement(
        material_property->get_state()[i]);

  // Execute the refinement
  triangulation.execute_coarsening_and_refinement();

  // Update MaterialProperty DoFHandler and resize the state vectors
  material_property->reinit_dofs();

  // Update the AffineConstraints and resize the solution
  thermal_physics->setup_dofs();
  thermal_physics->initialize_dof_vector(solution);
  solution_host.reinit(solution.get_partitioner());

  // Interpolate the solution and the state onto the new mesh
  solution_transfer.interpolate(solution_host);
  solution.import(solution_host, dealii::VectorOperation::insert);
  for (unsigned int i = 0;
       i < static_cast<unsigned int>(adamantine::MaterialState::SIZE); ++i)
    material_state[i].interpolate(material_property->get_state()[i]);
  // Update the material states in the ThermalOperator
  thermal_physics->get_state_from_material_properties();

#if ADAMANTINE_DEBUG
  // Check that we are not losing material
  std::array<dealii::LA::distributed::Vector<double, dealii::MemorySpace::Host>,
             static_cast<unsigned int>(adamantine::MaterialState::SIZE)>
      state = material_property->get_state();
  unsigned int const local_size = state[0].locally_owned_size();
  unsigned int constexpr n_material_states =
      static_cast<unsigned int>(adamantine::MaterialState::SIZE);
  for (unsigned int i = 0; i < local_size; ++i)
  {
    double material_ratio = 0.;
    for (unsigned int j = 0; j < n_material_states; ++j)
      material_ratio += state[j].local_element(i);
    adamantine::ASSERT(std::abs(material_ratio - 1.) < 1e-14,
                       "Material is lost.");
  }
#endif
}
#endif

template <int dim>
std::vector<typename dealii::parallel::distributed::Triangulation<
    dim>::active_cell_iterator>
compute_cells_to_refine(
    dealii::parallel::distributed::Triangulation<dim> &triangulation,
    double const time, double const next_refinement_time,
    unsigned int const n_time_steps,
    std::vector<std::shared_ptr<adamantine::HeatSource<dim>>> &heat_sources,
    double const current_source_height, double const refinement_beam_cutoff)
{

  // Compute the position of the beams between time and next_refinement_time and
  // refine the mesh where the source is greater than refinement_beam_cutoff.
  // This cut-off is due to the fact that the source is gaussian and thus never
  // strictly zero. If the beams intersect, some cells will appear twice in the
  // vector. This is not a problem.
  std::vector<typename dealii::parallel::distributed::Triangulation<
      dim>::active_cell_iterator>
      cells_to_refine;
  for (unsigned int i = 0; i < n_time_steps; ++i)
  {
    double const current_time = time + static_cast<double>(i) /
                                           static_cast<double>(n_time_steps) *
                                           (next_refinement_time - time);
    for (auto &beam : heat_sources)
    {
      for (auto cell : dealii::filter_iterators(
               triangulation.active_cell_iterators(),
               dealii::IteratorFilters::LocallyOwnedCell()))
      {
        if (beam->value(cell->center(), current_time, current_source_height) >
            refinement_beam_cutoff)
        {
          cells_to_refine.push_back(cell);
        }
      }
    }
  }

  return cells_to_refine;
}

template <int dim, int fe_degree, typename MemorySpaceType>
void refine_mesh(
    std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> &thermal_physics,
    dealii::LA::distributed::Vector<double, MemorySpaceType> &solution,
    std::vector<std::shared_ptr<adamantine::HeatSource<dim>>> &heat_sources,
    double const time, double const next_refinement_time,
    unsigned int const time_steps_refinement,
    boost::property_tree::ptree const &refinement_database)
{
#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_FUNCTION;
#endif
  dealii::DoFHandler<dim> &dof_handler = thermal_physics->get_dof_handler();
  // Use the Kelly error estimator to refine the mesh. This is done so that the
  // part of the domain that were heated stay refined.
  // PropertyTreeInput refinement.n_heat_refinements
  unsigned int const n_kelly_refinements =
      refinement_database.get("n_heat_refinements", 2);
  double coarsening_fraction = 0.3;
  double refining_fraction = 0.6;
  // PropertyTreeInput refinement.heat_cell_ratio
  double cells_fraction = refinement_database.get("heat_cell_ratio", 1.);
  dealii::parallel::distributed::Triangulation<dim> &triangulation =
      dynamic_cast<dealii::parallel::distributed::Triangulation<dim> &>(
          const_cast<dealii::Triangulation<dim> &>(
              dof_handler.get_triangulation()));
  // Number of times the mesh on the beam paths will be refined and maximum
  // number of time a cell can be refined.
  // PropertyTreeInput refinement.n_beam_refinements
  unsigned int const n_beam_refinements =
      refinement_database.get("n_beam_refinements", 2);
  // PropertyTreeInput refinement.max_level
  int max_level = refinement_database.get<int>("max_level");

  // PropertyTreeInput refinement.beam_cutoff
  const double refinement_beam_cutoff =
      refinement_database.get<double>("beam_cutoff", 1.0e-15);

  for (unsigned int i = 0; i < n_kelly_refinements; ++i)
  {
    // Estimate the error. For simplicity, always use dealii::QGauss
    dealii::Vector<float> estimated_error_per_cell =
        estimate_error(triangulation, dof_handler, fe_degree, solution);

    // Flag the cells for refinement.
    unsigned int new_n_cells = static_cast<unsigned int>(
        cells_fraction *
        static_cast<double>(triangulation.n_global_active_cells()));
    dealii::GridRefinement::refine_and_coarsen_fixed_fraction(
        triangulation, estimated_error_per_cell, refining_fraction,
        coarsening_fraction, new_n_cells);

    // Don't refine cells that are already as much refined as it is allowed.
    for (auto cell :
         dealii::filter_iterators(triangulation.active_cell_iterators(),
                                  dealii::IteratorFilters::LocallyOwnedCell()))
      if (cell->level() >= max_level)
        cell->clear_refine_flag();

    // Execute the refinement and transfer the solution onto the new mesh.
    refine_and_transfer(thermal_physics, dof_handler, solution);
  }

  // Refine the mesh along the trajectory of the sources.
  double current_source_height =
      dynamic_cast<adamantine::ThermalPhysics<dim, fe_degree, MemorySpaceType,
                                              dealii::QGauss<1>> *>(
          thermal_physics.get())
          ? dynamic_cast<adamantine::ThermalPhysics<
                dim, fe_degree, MemorySpaceType, dealii::QGauss<1>> *>(
                thermal_physics.get())
                ->get_current_source_height()
          : dynamic_cast<adamantine::ThermalPhysics<
                dim, fe_degree, MemorySpaceType, dealii::QGaussLobatto<1>> *>(
                thermal_physics.get())
                ->get_current_source_height();

  for (unsigned int i = 0; i < n_beam_refinements; ++i)
  {
    // Compute the cells to be refined.
    std::vector<typename dealii::parallel::distributed::Triangulation<
        dim>::active_cell_iterator>
        cells_to_refine = compute_cells_to_refine(
            triangulation, time, next_refinement_time, time_steps_refinement,
            heat_sources, current_source_height, refinement_beam_cutoff);

    // PropertyTreeInput refinement.coarsen_after_beam
    const bool coarsen_after_beam =
        refinement_database.get<bool>("coarsen_after_beam", false);

    // If coarsening is allowed, set the coarsening flag everywhere
    if (coarsen_after_beam)
    {
      for (auto cell : dealii::filter_iterators(
               triangulation.active_cell_iterators(),
               dealii::IteratorFilters::LocallyOwnedCell()))
      {
        if (cell->level() > 0)
          cell->set_coarsen_flag();
      }
    }

    // Flag the cells for refinement.
    for (auto &cell : cells_to_refine)
    {
      if (coarsen_after_beam)
        cell->clear_coarsen_flag();
      if (cell->level() < max_level)
        cell->set_refine_flag();
    }

    // Execute the refinement and transfer the solution onto the new mesh.
    refine_and_transfer(thermal_physics, dof_handler, solution);
  }

  // Recompute the inverse of the mass matrix
  thermal_physics->compute_inverse_mass_matrix();
}

template <int dim, typename MemorySpaceType>
void refine_mesh(
    std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> &thermal_physics,
    dealii::LA::distributed::Vector<double, MemorySpaceType> &solution,
    std::vector<std::shared_ptr<adamantine::HeatSource<dim>>> &heat_sources,
    double const time, double const next_refinement_time,
    unsigned int const time_steps_refinement,
    boost::property_tree::ptree const &refinement_database,
    unsigned int const fe_degree)
{
  switch (fe_degree)
  {
  case 1:
  {
    refine_mesh<dim, 1>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 2:
  {
    refine_mesh<dim, 2>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 3:
  {
    refine_mesh<dim, 3>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 4:
  {
    refine_mesh<dim, 4>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 5:
  {
    refine_mesh<dim, 5>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 6:
  {
    refine_mesh<dim, 6>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 7:
  {
    refine_mesh<dim, 7>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 8:
  {
    refine_mesh<dim, 8>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 9:
  {
    refine_mesh<dim, 9>(thermal_physics, solution, heat_sources, time,
                        next_refinement_time, time_steps_refinement,
                        refinement_database);
    break;
  }
  case 10:
  {
    refine_mesh<dim, 10>(thermal_physics, solution, heat_sources, time,
                         next_refinement_time, time_steps_refinement,
                         refinement_database);
    break;
  }
  default:
  {
    adamantine::ASSERT_THROW(false, "fe_degree should be between 1 and 10.");
  }
  }
}

template <int dim, typename MemorySpaceType>
dealii::LinearAlgebra::distributed::Vector<double, MemorySpaceType>
run(MPI_Comm const &communicator, boost::property_tree::ptree const &database,
    std::vector<adamantine::Timer> &timers)
{
#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_FUNCTION;
#endif

  // Extract property tree children
  boost::property_tree::ptree geometry_database =
      database.get_child("geometry");
  boost::property_tree::ptree discretization_database =
      database.get_child("discretization");
  boost::property_tree::ptree time_stepping_database =
      database.get_child("time_stepping");
  boost::property_tree::ptree post_processor_database =
      database.get_child("post_processor");
  boost::property_tree::ptree refinement_database =
      database.get_child("refinement");

  // PropertyTreeInput discretization.fe_degree
  unsigned int const fe_degree =
      discretization_database.get<unsigned int>("fe_degree");
  // PropertyTreeInput discretization.quadrature
  std::string quadrature_type =
      discretization_database.get("quadrature", "gauss");
  std::transform(quadrature_type.begin(), quadrature_type.end(),
                 quadrature_type.begin(),
                 [](unsigned char c) { return std::tolower(c); });
  // PropertyTreeInput materials.initial_temperature
  double const initial_temperature =
      database.get("materials.initial_temperature", 300.);
  // PropertyTreeInput materials.new_material_temperature
  double const new_material_temperature =
      database.get("materials.new_material_temperature", 300.);
  adamantine::Geometry<dim> geometry(communicator, geometry_database);

  std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>> thermal_physics;
  std::vector<std::shared_ptr<adamantine::HeatSource<dim>>> &heat_sources =
      initialize_thermal_physics<dim>(fe_degree, quadrature_type, communicator,
                                      database, geometry, thermal_physics);

  adamantine::PostProcessor<dim> post_processor(
      communicator, post_processor_database, thermal_physics->get_dof_handler(),
      thermal_physics->get_material_property());

  thermal_physics->setup_dofs();
  thermal_physics->compute_inverse_mass_matrix();
  dealii::LA::distributed::Vector<double, MemorySpaceType> solution;
  thermal_physics->initialize_dof_vector(initial_temperature, solution);
  thermal_physics->get_state_from_material_properties();

  unsigned int progress = 0;
  unsigned int cycle = 0;
  unsigned int n_time_step = 0;
  double time = 0.;
  // Output the initial solution
  dealii::AffineConstraints<double> &affine_constraints =
      thermal_physics->get_affine_constraints();
  output_pvtu(post_processor, cycle, n_time_step, time, affine_constraints,
              solution, timers);
  ++n_time_step;

  // PropertyTreeInput refinement.verbose
  bool const verbose_refinement = refinement_database.get("verbose", false);
  // PropertyTreeInput refinement.time_steps_between_refinement
  unsigned int const time_steps_refinement =
      refinement_database.get("time_steps_between_refinement", 10);
  double next_refinement_time = time;
  // PropertyTreeInput time_stepping.time_step
  double time_step = time_stepping_database.get<double>("time_step");
  // PropertyTreeInput time_stepping.duration
  double const duration = time_stepping_database.get<double>("duration");
  // PropertyTreeInput post_processor.time_steps_between_output
  unsigned int const time_steps_output =
      post_processor_database.get("time_steps_between_output", 1);

  auto [material_deposition_boxes, deposition_times] =
      adamantine::create_material_deposition_boxes<dim>(geometry_database,
                                                        heat_sources);

  // Unless we use an embedded method, we know in advance the time step.

  // Thus we can get for each time step, the list of elements that we will need
  // to activate. This list will be invalidated every time we refine the mesh.
  timers[adamantine::add_material_search].start();

  auto elements_to_activate = adamantine::get_elements_to_activate(
      thermal_physics->get_dof_handler(), material_deposition_boxes);
  timers[adamantine::add_material_search].stop();

#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_LOOP_BEGIN(main_loop_id, "main_loop");
#endif
  while (time < duration)
  {
#ifdef ADAMANTINE_WITH_CALIPER
    CALI_CXX_MARK_LOOP_ITERATION(main_loop_id, n_time_step - 1);
#endif
    if ((time + time_step) > duration)
      time_step = duration - time;
    unsigned int rank = dealii::Utilities::MPI::this_mpi_process(communicator);

    // Refine the mesh after time_steps_refinement time steps or when time
    // is greater or equal than the next predicted time for refinement. This
    // is necessary when using an embedded method.
    if (((n_time_step % time_steps_refinement) == 0) ||
        (time >= next_refinement_time))
    {
      next_refinement_time = time + time_steps_refinement * time_step;
      timers[adamantine::refine].start();
      refine_mesh(thermal_physics, solution, heat_sources, time,
                  next_refinement_time, time_steps_refinement,
                  refinement_database, fe_degree);
      timers[adamantine::refine].stop();
      if ((rank == 0) && (verbose_refinement == true))
        std::cout << "n_dofs: " << thermal_physics->get_dof_handler().n_dofs()
                  << std::endl;

      timers[adamantine::add_material_search].start();
      elements_to_activate = adamantine::get_elements_to_activate(
          thermal_physics->get_dof_handler(), material_deposition_boxes);
      timers[adamantine::add_material_search].stop();
    }

    // Add material if necessary.

    // We use an epsilon to get the "expected" behavior when the deposition time
    // and the time match should match exactly but don't because of floating
    // point accuracy.
    timers[adamantine::add_material_activate].start();

    double const eps = time_step / 1e12;
    auto activation_start =
        std::lower_bound(deposition_times.begin(), deposition_times.end(),
                         time - eps) -
        deposition_times.begin();
    auto activation_end =
        std::lower_bound(deposition_times.begin(), deposition_times.end(),
                         time + time_step - eps) -
        deposition_times.begin();
    for (unsigned int i = activation_start; i < activation_end; ++i)
      thermal_physics->add_material(elements_to_activate[i],
                                    new_material_temperature, solution);

    if ((rank == 0) && (verbose_refinement == true) &&
        (activation_end - activation_start > 0))
      std::cout << "n_dofs: " << thermal_physics->get_dof_handler().n_dofs()
                << std::endl;
    // Remove elements that have been activated
    elements_to_activate.erase(elements_to_activate.begin() + activation_start,
                               elements_to_activate.begin() + activation_end);
    deposition_times.erase(deposition_times.begin() + activation_start,
                           deposition_times.begin() + activation_end);

    material_deposition_boxes.erase(
        material_deposition_boxes.begin() + activation_start,
        material_deposition_boxes.begin() + activation_end);

    timers[adamantine::add_material_activate].stop();

    // Time can be different than time + time_step if an embedded scheme is
    // used. Note that this is a problem when adding material because it
    // means that the amount of material that needs to be added is not
    // known.
#if ADAMANTINE_DEBUG
    double const old_time = time;
    bool const adding_material =
        (activation_start == activation_end) ? false : true;
#endif
    timers[adamantine::evol_time].start();
    time = thermal_physics->evolve_one_time_step(time, time_step, solution,
                                                 timers);
#if ADAMANTINE_DEBUG
    adamantine::ASSERT(!adding_material ||
                           ((time - old_time) < time_step / 1e-9),
                       "Unexpected time step while adding material.");
#endif
    timers[adamantine::evol_time].stop();

    // Get the new time step
    time_step = thermal_physics->get_delta_t_guess();

    // Output progress on screen
    if (rank == 0)
    {
      double adim_time = time / (duration / 10.);
      double int_part = 0;
      std::modf(adim_time, &int_part);
      if (int_part > progress)
      {
        std::cout << int_part * 10 << '%' << " completed" << std::endl;
        ++progress;
      }
    }

    // Output the solution
    if (n_time_step % time_steps_output == 0)
    {
      thermal_physics->set_state_to_material_properties();
      output_pvtu(post_processor, cycle, n_time_step, time, affine_constraints,
                  solution, timers);
    }
    ++n_time_step;
  }

#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_LOOP_END(main_loop_id);
#endif

  post_processor.output_pvd();

  // This is only used for integration test
  return solution;
}

template <int dim, typename MemorySpaceType>
std::vector<dealii::LinearAlgebra::distributed::Vector<double, MemorySpaceType>>
run_ensemble(MPI_Comm const &communicator,
             boost::property_tree::ptree const &database,
             std::vector<adamantine::Timer> &timers)
{
#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_FUNCTION;
#endif

  // Extract property tree children
  boost::property_tree::ptree geometry_database =
      database.get_child("geometry");
  boost::property_tree::ptree discretization_database =
      database.get_child("discretization");
  boost::property_tree::ptree time_stepping_database =
      database.get_child("time_stepping");
  boost::property_tree::ptree post_processor_database =
      database.get_child("post_processor");
  boost::property_tree::ptree refinement_database =
      database.get_child("refinement");
  boost::property_tree::ptree ensemble_database =
      database.get_child("ensemble");

  // PropertyTreeInput discretization.fe_degree
  unsigned int const fe_degree =
      discretization_database.get<unsigned int>("fe_degree");
  // PropertyTreeInput discretization.quadrature
  std::string quadrature_type =
      discretization_database.get("quadrature", "gauss");
  std::transform(quadrature_type.begin(), quadrature_type.end(),
                 quadrature_type.begin(),
                 [](unsigned char c) { return std::tolower(c); });

  // PropertyTreeInput materials.initial_temperature
  double const initial_temperature =
      database.get("materials.initial_temperature", 300.);
  // Get the nominal (mean) values of the ensemble parameters
  // PropertyTreeInput materials.new_material_temperature
  double const new_material_temperature_mean =
      database.get("materials.new_material_temperature", 300.);

  // PropertyTreeInput sources.n_beams
  unsigned int const n_beams = database.get<unsigned int>("sources.n_beams");
  double beam_0_max_power_mean;
  if (n_beams > 0)
  {
    // PropertyTreeInput sources.beam_0.max_power
    beam_0_max_power_mean = database.get<double>("sources.beam_0.max_power");
  }
  else
  {
    beam_0_max_power_mean = 0;
  }

  // Set up the ensemble members
  // There might be a more efficient way to share some of these objects between
  // ensemble members. For now, we'll do the simpler approach of duplicating
  // everything.
  // PropertyTreeInput ensemble.ensemble_size
  const unsigned int ensemble_size = ensemble_database.get("ensemble_size", 5);

  // PropertyTreeInput ensemble.new_material_temperature_stddev
  const double new_material_temperature_stddev =
      ensemble_database.get("new_material_temperature_stddev", 0.0);

  std::vector<double> new_material_temperature =
      adamantine::fill_and_sync_random_vector(ensemble_size,
                                              new_material_temperature_mean,
                                              new_material_temperature_stddev);

  // PropertyTreeInput ensemble.beam_0_max_power_stddev
  const double beam_0_max_power_stddev =
      ensemble_database.get("beam_0_max_power_stddev", 0.0);

  std::vector<double> beam_0_max_power =
      adamantine::fill_and_sync_random_vector(
          ensemble_size, beam_0_max_power_mean, beam_0_max_power_stddev);

  // Create a new property tree database for each ensemble member
  std::vector<boost::property_tree::ptree> database_ensemble(ensemble_size,
                                                             database);

  std::vector<std::unique_ptr<adamantine::Physics<dim, MemorySpaceType>>>
      thermal_physics_ensemble(ensemble_size);

  std::vector<std::vector<std::shared_ptr<adamantine::HeatSource<dim>>>>
      heat_sources_ensemble(ensemble_size);

  std::vector<dealii::LA::distributed::Vector<double, MemorySpaceType>>
      solution_ensemble(ensemble_size);

  std::vector<std::unique_ptr<adamantine::Geometry<dim>>> geometry_ensemble;

  std::vector<std::unique_ptr<adamantine::PostProcessor<dim>>>
      post_processor_ensemble;

  for (unsigned int member = 0; member < ensemble_size; ++member)
  {
    // Edit the database for the ensemble
    if (n_beams > 0)
    {
      // PropertyTreeInput sources.beam_0.max_power
      database_ensemble[member].put("sources.beam_0.max_power",
                                    beam_0_max_power[member]);
    }

    geometry_ensemble.push_back(std::make_unique<adamantine::Geometry<dim>>(
        communicator, geometry_database));

    heat_sources_ensemble[member] = initialize_thermal_physics<dim>(
        fe_degree, quadrature_type, communicator, database_ensemble[member],
        *geometry_ensemble[member], thermal_physics_ensemble[member]);

    thermal_physics_ensemble[member]->setup_dofs();
    thermal_physics_ensemble[member]->compute_inverse_mass_matrix();

    thermal_physics_ensemble[member]->initialize_dof_vector(
        initial_temperature, solution_ensemble[member]);
    thermal_physics_ensemble[member]->get_state_from_material_properties();

    post_processor_ensemble.push_back(
        std::make_unique<adamantine::PostProcessor<dim>>(
            communicator, post_processor_database,
            thermal_physics_ensemble[member]->get_dof_handler(),
            thermal_physics_ensemble[member]->get_material_property(), member));
  }

  unsigned int progress = 0;
  unsigned int cycle = 0;
  unsigned int n_time_step = 0;
  double time = 0.;

  // Output the initial solution
  std::vector<dealii::AffineConstraints<double>> affine_constraints_ensemble;
  for (unsigned int member = 0; member < ensemble_size; ++member)
  {
    affine_constraints_ensemble.push_back(
        thermal_physics_ensemble[member]->get_affine_constraints());

    output_pvtu(*post_processor_ensemble[member], cycle, n_time_step, time,
                affine_constraints_ensemble[member], solution_ensemble[member],
                timers);
  }

  // Increment the time step
  ++n_time_step;

  // PropertyTreeInput refinement.verbose
  bool const verbose_refinement = refinement_database.get("verbose", false);
  // PropertyTreeInput refinement.time_steps_between_refinement
  unsigned int const time_steps_refinement =
      refinement_database.get("time_steps_between_refinement", 10);
  double next_refinement_time = time;
  // PropertyTreeInput time_stepping.time_step
  double time_step = time_stepping_database.get<double>("time_step");
  // PropertyTreeInput time_stepping.duration
  double const duration = time_stepping_database.get<double>("duration");
  // PropertyTreeInput post_processor.time_steps_between_output
  unsigned int const time_steps_output =
      post_processor_database.get("time_steps_between_output", 1);

  // For now assume that all ensemble members share the same geometry (they have
  // independent adamantine::Geometry objects, but all are constructed from
  // identical parameters), base new additions on the 0th ensemble member
  auto [material_deposition_boxes, deposition_times] =
      adamantine::create_material_deposition_boxes<dim>(
          geometry_database, heat_sources_ensemble[0]);

  // Unless we use an embedded method, we know in advance the time step.

  // Thus we can get for each time step, the list of elements that we will need
  // to activate. This list will be invalidated every time we refine the mesh.
  timers[adamantine::add_material_search].start();

  auto elements_to_activate = adamantine::get_elements_to_activate(
      thermal_physics_ensemble[0]->get_dof_handler(),
      material_deposition_boxes);
  timers[adamantine::add_material_search].stop();

#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_LOOP_BEGIN(main_loop_id, "main_loop");
#endif
  while (time < duration)
  {

#ifdef ADAMANTINE_WITH_CALIPER
    CALI_CXX_MARK_LOOP_ITERATION(main_loop_id, n_time_step - 1);
#endif
    if ((time + time_step) > duration)
      time_step = duration - time;
    unsigned int rank = dealii::Utilities::MPI::this_mpi_process(communicator);

    // Refine the mesh after time_steps_refinement time steps or when time
    // is greater or equal than the next predicted time for refinement. This
    // is necessary when using an embedded method.
    if (((n_time_step % time_steps_refinement) == 0) ||
        (time >= next_refinement_time))
    {
      next_refinement_time = time + time_steps_refinement * time_step;
      timers[adamantine::refine].start();

      for (unsigned int member = 0; member < ensemble_size; ++member)
      {
        refine_mesh(thermal_physics_ensemble[member], solution_ensemble[member],
                    heat_sources_ensemble[member], time, next_refinement_time,
                    time_steps_refinement, refinement_database, fe_degree);
      }
      timers[adamantine::refine].stop();
      if ((rank == 0) && (verbose_refinement == true))
        std::cout << "n_dofs: "
                  << thermal_physics_ensemble[0]->get_dof_handler().n_dofs()
                  << std::endl;

      timers[adamantine::add_material_search].start();
      elements_to_activate = adamantine::get_elements_to_activate(
          thermal_physics_ensemble[0]->get_dof_handler(),
          material_deposition_boxes);
      timers[adamantine::add_material_search].stop();
    }

    // Add material if necessary.

    // We use an epsilon to get the "expected" behavior when the deposition time
    // and the time match should match exactly but don't because of floating
    // point accuracy.
    timers[adamantine::add_material_activate].start();

    double const eps = time_step / 1e12;
    auto activation_start =
        std::lower_bound(deposition_times.begin(), deposition_times.end(),
                         time - eps) -
        deposition_times.begin();
    auto activation_end =
        std::lower_bound(deposition_times.begin(), deposition_times.end(),
                         time + time_step - eps) -
        deposition_times.begin();
    for (unsigned int i = activation_start; i < activation_end; ++i)
    {
      for (unsigned int member = 0; member < ensemble_size; ++member)
      {
        thermal_physics_ensemble[member]->add_material(
            elements_to_activate[i], new_material_temperature[member],
            solution_ensemble[member]);
      }
    }

    if ((rank == 0) && (verbose_refinement == true) &&
        (activation_end - activation_start > 0))
      std::cout << "n_dofs: "
                << thermal_physics_ensemble[0]->get_dof_handler().n_dofs()
                << std::endl;
    // Remove elements that have been activated
    elements_to_activate.erase(elements_to_activate.begin() + activation_start,
                               elements_to_activate.begin() + activation_end);
    deposition_times.erase(deposition_times.begin() + activation_start,
                           deposition_times.begin() + activation_end);

    material_deposition_boxes.erase(
        material_deposition_boxes.begin() + activation_start,
        material_deposition_boxes.begin() + activation_end);

    timers[adamantine::add_material_activate].stop();

    // Time can be different than time + time_step if an embedded scheme is
    // used. Note that this is a problem when adding material because it
    // means that the amount of material that needs to be added is not
    // known.
#if ADAMANTINE_DEBUG
    double const old_time = time;
    bool const adding_material =
        (activation_start == activation_end) ? false : true;
#endif
    timers[adamantine::evol_time].start();
    for (unsigned int member = 0; member < ensemble_size; ++member)
    {
      time = thermal_physics_ensemble[member]->evolve_one_time_step(
          time, time_step, solution_ensemble[member], timers);
    }
#if ADAMANTINE_DEBUG
    adamantine::ASSERT(!adding_material ||
                           ((time - old_time) < time_step / 1e-9),
                       "Unexpected time step while adding material.");
#endif
    timers[adamantine::evol_time].stop();

    // Get the new time step (needs to be the same for all ensemble members,
    // obtained from the 0th member)
    time_step = thermal_physics_ensemble[0]->get_delta_t_guess();

    // Output progress on screen
    if (rank == 0)
    {
      double adim_time = time / (duration / 10.);
      double int_part = 0;
      std::modf(adim_time, &int_part);
      if (int_part > progress)
      {
        std::cout << int_part * 10 << '%' << " completed" << std::endl;
        ++progress;
      }
    }

    // Output the solution
    if (n_time_step % time_steps_output == 0)
    {
      for (unsigned int member = 0; member < ensemble_size; ++member)
      {
        thermal_physics_ensemble[member]->set_state_to_material_properties();
        output_pvtu(*post_processor_ensemble[member], cycle, n_time_step, time,
                    affine_constraints_ensemble[member],
                    solution_ensemble[member], timers);
      }
    }

    ++n_time_step;
  }

#ifdef ADAMANTINE_WITH_CALIPER
  CALI_CXX_MARK_LOOP_END(main_loop_id);
#endif

  for (unsigned int member = 0; member < ensemble_size; ++member)
  {
    post_processor_ensemble[member]->output_pvd();
  }

  // This is only used for integration test
  return solution_ensemble;
}
#endif


// Copyright (C) 2018  Davis E. King (davis@dlib.net)
// License: Boost Software License   See LICENSE.txt for the full license.
#include "opaque_types.h"
#include <dlib/python.h>
#include "dlib/pixel.h"
#include <dlib/image_transforms.h>
#include <dlib/image_processing.h>

using namespace dlib;
using namespace std;

namespace py = pybind11;

// ----------------------------------------------------------------------------------------

template <typename T>
py::array convert_image_scaled (
    const numpy_image<T>& img,
    const string& dtype,
    const double thresh = 4
)
{
    if (dtype == "uint8")    {numpy_image<uint8_t>   out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "uint16")   {numpy_image<uint16_t>  out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "uint32")   {numpy_image<uint32_t>  out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "uint64")   {numpy_image<uint64_t>  out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "int8")     {numpy_image<int8_t>    out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "int16")    {numpy_image<int16_t>   out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "int32")    {numpy_image<int32_t>   out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "int64")    {numpy_image<int64_t>   out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "float32")  {numpy_image<float>     out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "float64")  {numpy_image<double>    out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "float")    {numpy_image<float>     out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "double")   {numpy_image<double>    out; assign_image_scaled(out, img, thresh); return out;}
    if (dtype == "rgb_pixel"){numpy_image<rgb_pixel> out; assign_image_scaled(out, img, thresh); return out;}

    throw dlib::error("convert_image_scaled() called with invalid dtype, must be one of these strings: \n"
        "uint8, int8, uint16, int16, uint32, int32, uint64, int64, float32, float, float64, double, or rgb_pixel");
}

// ----------------------------------------------------------------------------------------

struct py_pyramid_down
{

    void dostuff(point) {}

    py_pyramid_down(
    ) = default;

    py_pyramid_down (
        unsigned int N_
    ) : N(N_)
    {
        DLIB_CASSERT( 1 <= N && N <= 20, "pyramid downsampling rate must be between 1 and 20.");
    }

    unsigned int pyramid_downsampling_rate (
    ) const { return N; }

    template <typename T>
    dlib::vector<double,2> point_down (
        const dlib::vector<T,2>& pp
    ) const
    {
        dpoint p = pp;
        switch(N)
        {
            case 1: return pyr1.point_down(p);
            case 2: return pyr2.point_down(p);
            case 3: return pyr3.point_down(p);
            case 4: return pyr4.point_down(p);
            case 5: return pyr5.point_down(p);
            case 6: return pyr6.point_down(p);
            case 7: return pyr7.point_down(p);
            case 8: return pyr8.point_down(p);
            case 9: return pyr9.point_down(p);
            case 10: return pyr10.point_down(p);
            case 11: return pyr11.point_down(p);
            case 12: return pyr12.point_down(p);
            case 13: return pyr13.point_down(p);
            case 14: return pyr14.point_down(p);
            case 15: return pyr15.point_down(p);
            case 16: return pyr16.point_down(p);
            case 17: return pyr17.point_down(p);
            case 18: return pyr18.point_down(p);
            case 19: return pyr19.point_down(p);
            case 20: return pyr20.point_down(p);
        }

        DLIB_CASSERT(false, "This should never happen");
    }

    template <typename T>
    dlib::vector<double,2> point_up (
        const dlib::vector<T,2>& pp
    ) const
    {
        dpoint p = pp;
        switch(N)
        {
            case 1: return pyr1.point_up(p);
            case 2: return pyr2.point_up(p);
            case 3: return pyr3.point_up(p);
            case 4: return pyr4.point_up(p);
            case 5: return pyr5.point_up(p);
            case 6: return pyr6.point_up(p);
            case 7: return pyr7.point_up(p);
            case 8: return pyr8.point_up(p);
            case 9: return pyr9.point_up(p);
            case 10: return pyr10.point_up(p);
            case 11: return pyr11.point_up(p);
            case 12: return pyr12.point_up(p);
            case 13: return pyr13.point_up(p);
            case 14: return pyr14.point_up(p);
            case 15: return pyr15.point_up(p);
            case 16: return pyr16.point_up(p);
            case 17: return pyr17.point_up(p);
            case 18: return pyr18.point_up(p);
            case 19: return pyr19.point_up(p);
            case 20: return pyr20.point_up(p);
        }
        DLIB_CASSERT(false, "This should never happen");
    }

// -----------------------------

    template <typename T>
    dlib::vector<double,2> point_down2 (
        const dlib::vector<T,2>& p,
        unsigned int levels
    ) const
    {
        dlib::vector<double,2> temp = p;
        for (unsigned int i = 0; i < levels; ++i)
            temp = point_down(temp);
        return temp;
    }

    template <typename T>
    dlib::vector<double,2> point_up2 (
        const dlib::vector<T,2>& p,
        unsigned int levels
    ) const
    {
        dlib::vector<double,2> temp = p;
        for (unsigned int i = 0; i < levels; ++i)
            temp = point_up(temp);
        return temp;
    }

// -----------------------------

    template <typename rect_type>
    rect_type rect_up (
        const rect_type& rect
    ) const
    {
        return rect_type(point_up(rect.tl_corner()), point_up(rect.br_corner()));
    }

    template <typename rect_type>
    rect_type rect_up2 (
        const rect_type& rect,
        unsigned int levels
    ) const
    {
        return rect_type(point_up2(rect.tl_corner(),levels), point_up2(rect.br_corner(),levels));
    }

// -----------------------------

    template <typename rect_type>
    rect_type rect_down (
        const rect_type& rect
    ) const
    {
        return rect_type(point_down(rect.tl_corner()), point_down(rect.br_corner()));
    }

    template <typename rect_type>
    rect_type rect_down2 (
        const rect_type& rect,
        unsigned int levels
    ) const
    {
        return rect_type(point_down2(rect.tl_corner(),levels), point_down2(rect.br_corner(),levels));
    }

    template <
        typename T
        >
    numpy_image<T> down (
        const numpy_image<T>& img
    ) const
    {

        numpy_image<T> down;
        switch(N)
        {
            case 1: pyr1(img,down); break;
            case 2: pyr2(img,down); break;
            case 3: pyr3(img,down); break;
            case 4: pyr4(img,down); break;
            case 5: pyr5(img,down); break;
            case 6: pyr6(img,down); break;
            case 7: pyr7(img,down); break;
            case 8: pyr8(img,down); break;
            case 9: pyr9(img,down); break;
            case 10: pyr10(img,down); break;
            case 11: pyr11(img,down); break;
            case 12: pyr12(img,down); break;
            case 13: pyr13(img,down); break;
            case 14: pyr14(img,down); break;
            case 15: pyr15(img,down); break;
            case 16: pyr16(img,down); break;
            case 17: pyr17(img,down); break;
            case 18: pyr18(img,down); break;
            case 19: pyr19(img,down); break;
            case 20: pyr20(img,down); break;
        }

        return down;
    }

private:
    unsigned int N = 2;

    pyramid_down<1> pyr1;
    pyramid_down<2> pyr2;
    pyramid_down<3> pyr3;
    pyramid_down<4> pyr4;
    pyramid_down<5> pyr5;
    pyramid_down<6> pyr6;
    pyramid_down<7> pyr7;
    pyramid_down<8> pyr8;
    pyramid_down<9> pyr9;
    pyramid_down<10> pyr10;
    pyramid_down<11> pyr11;
    pyramid_down<12> pyr12;
    pyramid_down<13> pyr13;
    pyramid_down<14> pyr14;
    pyramid_down<15> pyr15;
    pyramid_down<16> pyr16;
    pyramid_down<17> pyr17;
    pyramid_down<18> pyr18;
    pyramid_down<19> pyr19;
    pyramid_down<20> pyr20;

};

// ----------------------------------------------------------------------------------------

py::tuple py_find_bright_lines (
    const numpy_image<float>& xx,
    const numpy_image<float>& xy,
    const numpy_image<float>& yy
)
{
    numpy_image<float> horz, vert;
    find_bright_lines(xx,xy,yy,horz,vert);
    return py::make_tuple(horz,vert);
}

py::tuple py_find_dark_lines (
    const numpy_image<float>& xx,
    const numpy_image<float>& xy,
    const numpy_image<float>& yy
)
{
    numpy_image<float> horz, vert;
    find_dark_lines(xx,xy,yy,horz,vert);
    return py::make_tuple(horz,vert);
}

numpy_image<float> py_find_bright_keypoints (
    const numpy_image<float>& xx,
    const numpy_image<float>& xy,
    const numpy_image<float>& yy
)
{
    numpy_image<float> sal;
    find_bright_keypoints(xx,xy,yy,sal);
    return sal;
}

numpy_image<float> py_find_dark_keypoints (
    const numpy_image<float>& xx,
    const numpy_image<float>& xy,
    const numpy_image<float>& yy
)
{
    numpy_image<float> sal;
    find_dark_keypoints(xx,xy,yy,sal);
    return sal;
}

template <typename T>
py::tuple py_sobel_edge_detector (
    const numpy_image<T>& img
)
{
    numpy_image<float> horz, vert;
    sobel_edge_detector(img, horz, vert);
    return py::make_tuple(horz,vert);
}

numpy_image<float> py_suppress_non_maximum_edges (
    const numpy_image<float>& horz,
    const numpy_image<float>& vert
)
{
    numpy_image<float> out;
    suppress_non_maximum_edges(horz,vert,out);
    return out;
}

numpy_image<float> py_suppress_non_maximum_edges2 (
    const py::tuple& horz_and_vert_gradients
)
{
    numpy_image<float> out, horz, vert;
    horz = horz_and_vert_gradients[0];
    vert = horz_and_vert_gradients[1];
    suppress_non_maximum_edges(horz,vert,out);
    return out;
}

template <typename T>
std::vector<point> py_find_peaks (
    const numpy_image<T>& img,
    const double non_max_suppression_radius,
    const T& thresh
)
{
    return find_peaks(img, non_max_suppression_radius, thresh);
}

template <typename T>
std::vector<point> py_find_peaks2 (
    const numpy_image<T>& img,
    const double non_max_suppression_radius
)
{
    return find_peaks(img, non_max_suppression_radius, partition_pixels(img));
}

// ----------------------------------------------------------------------------------------

template <typename T>
numpy_image<unsigned char> py_hysteresis_threshold (
    const numpy_image<T>& img,
    T lower_thresh,
    T upper_thresh
)
{
    numpy_image<unsigned char> out;
    hysteresis_threshold(img, out, lower_thresh, upper_thresh);
    return out;
}

template <typename T>
numpy_image<unsigned char> py_hysteresis_threshold2 (
    const numpy_image<T>& img
)
{
    numpy_image<unsigned char> out;
    hysteresis_threshold(img, out);
    return out;
}

// ----------------------------------------------------------------------------------------

void bind_image_classes3(py::module& m)
{
    const char* docs;

    docs =
"requires \n\
    - thresh > 0 \n\
ensures \n\
    - Converts an image to a target pixel type.  dtype must be a string containing one of the following: \n\
      uint8, int8, uint16, int16, uint32, int32, uint64, int64, float32, float, float64, double, or rgb_pixel \n\
 \n\
      The contents of img will be scaled to fit the dynamic range of the target \n\
      pixel type.  The thresh parameter is used to filter source pixel values which \n\
      are outliers.  These outliers will saturate at the edge of the destination \n\
      image's dynamic range. \n\
    - Specifically, for all valid r and c: \n\
        - We scale img[r][c] into the dynamic range of the target pixel type.  This \n\
          is done using the mean and standard deviation of img. Call the mean M and \n\
          the standard deviation D.  Then the scaling from source to destination is \n\
          performed using the following mapping: \n\
            let SRC_UPPER  = min(M + thresh*D, max(img)) \n\
            let SRC_LOWER  = max(M - thresh*D, min(img)) \n\
            let DEST_UPPER = max value possible for the selected dtype.  \n\
            let DEST_LOWER = min value possible for the selected dtype. \n\
 \n\
            MAPPING: [SRC_LOWER, SRC_UPPER] -> [DEST_LOWER, DEST_UPPER] \n\
 \n\
          Where this mapping is a linear mapping of values from the left range \n\
          into the right range of values.  Source pixel values outside the left \n\
          range are modified to be at the appropriate end of the range.";
    /*!
        requires
            - thresh > 0
        ensures
            - Converts an image to a target pixel type.  dtype must be a string containing one of the following:
              uint8, int8, uint16, int16, uint32, int32, uint64, int64, float32, float, float64, double, or rgb_pixel

              The contents of img will be scaled to fit the dynamic range of the target
              pixel type.  The thresh parameter is used to filter source pixel values which
              are outliers.  These outliers will saturate at the edge of the destination
              image's dynamic range.
            - Specifically, for all valid r and c:
                - We scale img[r][c] into the dynamic range of the target pixel type.  This
                  is done using the mean and standard deviation of img. Call the mean M and
                  the standard deviation D.  Then the scaling from source to destination is
                  performed using the following mapping:
                    let SRC_UPPER  = min(M + thresh*D, max(img))
                    let SRC_LOWER  = max(M - thresh*D, min(img))
                    let DEST_UPPER = max value possible for the selected dtype.
                    let DEST_LOWER = min value possible for the selected dtype.

                    MAPPING: [SRC_LOWER, SRC_UPPER] -> [DEST_LOWER, DEST_UPPER]

                  Where this mapping is a linear mapping of values from the left range
                  into the right range of values.  Source pixel values outside the left
                  range are modified to be at the appropriate end of the range.
    !*/
    m.def("convert_image_scaled", convert_image_scaled<uint8_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<uint16_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<uint32_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<uint64_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<int8_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<int16_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<int32_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<int64_t>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<float>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<double>, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);
    m.def("convert_image_scaled", convert_image_scaled<rgb_pixel>, docs, py::arg("img"), py::arg("dtype"), py::arg("thresh")=4);

    const char* class_docs;

    class_docs =
"This is a simple object to help create image pyramids.  In particular, it \n\
downsamples images at a ratio of N to N-1. \n\
 \n\
Note that setting N to 1 means that this object functions like \n\
pyramid_disable (defined at the bottom of this file).   \n\
 \n\
WARNING, when mapping rectangles from one layer of a pyramid \n\
to another you might end up with rectangles which extend slightly  \n\
outside your images.  This is because points on the border of an  \n\
image at a higher pyramid layer might correspond to points outside  \n\
images at lower layers.  So just keep this in mind.  Note also \n\
that it's easy to deal with.  Just say something like this: \n\
    rect = rect.intersect(get_rect(my_image)); # keep rect inside my_image ";
        /*!
                This is a simple object to help create image pyramids.  In particular, it
                downsamples images at a ratio of N to N-1.

                Note that setting N to 1 means that this object functions like
                pyramid_disable (defined at the bottom of this file).

                WARNING, when mapping rectangles from one layer of a pyramid
                to another you might end up with rectangles which extend slightly
                outside your images.  This is because points on the border of an
                image at a higher pyramid layer might correspond to points outside
                images at lower layers.  So just keep this in mind.  Note also
                that it's easy to deal with.  Just say something like this:
                    rect = rect.intersect(get_rect(my_image)); # keep rect inside my_image
        !*/

    docs =
"- Downsamples img to make a new image that is roughly (pyramid_downsampling_rate()-1)/pyramid_downsampling_rate()  \n\
  times the size of the original image.   \n\
- The location of a point P in original image will show up at point point_down(P) \n\
  in the downsampled image.   \n\
- Note that some points on the border of the original image might correspond to  \n\
  points outside the downsampled image.";
        /*!
          - Downsamples img to make a new image that is roughly (pyramid_downsampling_rate()-1)/pyramid_downsampling_rate()
            times the size of the original image.
          - The location of a point P in original image will show up at point point_down(P)
            in the downsampled image.
          - Note that some points on the border of the original image might correspond to
            points outside the downsampled image.
        !*/
    py::class_<py_pyramid_down>(m, "pyramid_down", class_docs)
        .def(py::init<unsigned int>(), "Creates this class with the provided downsampling rate. i.e. pyramid_downsampling_rate()==N. \nN must be in the range 1 to 20.", py::arg("N"))
        .def(py::init<>(), "Creates this class with pyramid_downsampling_rate()==2")
        .def("pyramid_downsampling_rate", &py_pyramid_down::pyramid_downsampling_rate,
            "Returns a number N that defines the downsampling rate.  In particular, images are downsampled by a factor of N to N-1.")
        .def("point_up", &py_pyramid_down::point_up<long>,   py::arg("p"))
        .def("point_up", &py_pyramid_down::point_up<double>,
            "Maps from pixels in a downsampled image to pixels in the original image.",  py::arg("p"))
        .def("point_up", &py_pyramid_down::point_up2<long>,   py::arg("p"), py::arg("levels"))
        .def("point_up", &py_pyramid_down::point_up2<double>,
            "Applies point_up() to p levels times and returns the result.",  py::arg("p"), py::arg("levels"))
        .def("point_down", &py_pyramid_down::point_down<long>,   py::arg("p"))
        .def("point_down", &py_pyramid_down::point_down<double>,
            "Maps from pixels in a source image to the corresponding pixels in the downsampled image.", py::arg("p"))
        .def("point_down", &py_pyramid_down::point_down2<long>,   py::arg("p"), py::arg("levels"))
        .def("point_down", &py_pyramid_down::point_down2<double>, "Applies point_down() to p levels times and returns the result.",
            py::arg("p"), py::arg("levels"))
        .def("rect_down", &py_pyramid_down::rect_down<rectangle>,   py::arg("rect"))
        .def("rect_down", &py_pyramid_down::rect_down<drectangle>,
          "returns drectangle(point_down(rect.tl_corner()), point_down(rect.br_corner()));\n (i.e. maps rect into a downsampled)",
          py::arg("rect"))
        .def("rect_down", &py_pyramid_down::rect_down2<rectangle>,   py::arg("rect"), py::arg("levels"))
        .def("rect_down", &py_pyramid_down::rect_down2<drectangle>, "Applies rect_down() to rect levels times and returns the result.",
            py::arg("rect"), py::arg("levels"))
        .def("rect_up", &py_pyramid_down::rect_up<rectangle>,   py::arg("rect"))
        .def("rect_up", &py_pyramid_down::rect_up<drectangle>,
          "returns drectangle(point_up(rect.tl_corner()), point_up(rect.br_corner()));\n (i.e. maps rect into a parent image)",
            py::arg("rect"))
        .def("rect_up", &py_pyramid_down::rect_up2<rectangle>,   py::arg("rect"), py::arg("levels"))
        .def("rect_up", &py_pyramid_down::rect_up2<drectangle>,  "Applies rect_up() to rect levels times and returns the result.",
            py::arg("p"), py::arg("levels"))
        .def("__call__", &py_pyramid_down::down<uint8_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<uint16_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<uint32_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<uint64_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<int8_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<int16_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<int32_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<int64_t>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<float>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<double>,   py::arg("img"))
        .def("__call__", &py_pyramid_down::down<rgb_pixel>, docs,  py::arg("img"));

    docs =
"requires \n\
    - xx, xy, and yy all have the same dimensions. \n\
ensures \n\
    - This routine is similar to sobel_edge_detector(), except instead of finding \n\
      an edge it finds a bright/white line.  For example, the border between a \n\
      black piece of paper and a white table is an edge, but a curve drawn with a \n\
      pencil on a piece of paper makes a line.  Therefore, the output of this \n\
      routine is a vector field encoded in the horz and vert images, which are \n\
      returned in a tuple where the first element is horz and the second is vert. \n\
 \n\
      The vector obtains a large magnitude when centered on a bright line in an image and the \n\
      direction of the vector is perpendicular to the line.  To be very precise, \n\
      each vector points in the direction of greatest change in second derivative \n\
      and the magnitude of the vector encodes the derivative magnitude in that \n\
      direction.  Moreover, if the second derivative is positive then the output \n\
      vector is zero.  This zeroing if positive gradients causes the output to be \n\
      sensitive only to bright lines surrounded by darker pixels. \n\
 \n\
    - We assume that xx, xy, and yy are the 3 second order gradients of the image \n\
      in question.  You can obtain these gradients using the image_gradients class. \n\
    - The output images will have the same dimensions as the input images. ";
    /*!
        requires
            - xx, xy, and yy all have the same dimensions.
        ensures
            - This routine is similar to sobel_edge_detector(), except instead of finding
              an edge it finds a bright/white line.  For example, the border between a
              black piece of paper and a white table is an edge, but a curve drawn with a
              pencil on a piece of paper makes a line.  Therefore, the output of this
              routine is a vector field encoded in the horz and vert images, which are
              returned in a tuple where the first element is horz and the second is vert.

              The vector obtains a large magnitude when centered on a bright line in an image and the
              direction of the vector is perpendicular to the line.  To be very precise,
              each vector points in the direction of greatest change in second derivative
              and the magnitude of the vector encodes the derivative magnitude in that
              direction.  Moreover, if the second derivative is positive then the output
              vector is zero.  This zeroing if positive gradients causes the output to be
              sensitive only to bright lines surrounded by darker pixels.

            - We assume that xx, xy, and yy are the 3 second order gradients of the image
              in question.  You can obtain these gradients using the image_gradients class.
            - The output images will have the same dimensions as the input images.
    !*/
    m.def("find_bright_lines",     &py_find_bright_lines,     docs, py::arg("xx"), py::arg("xy"), py::arg("yy"));

    docs =
"requires \n\
    - xx, xy, and yy all have the same dimensions. \n\
ensures \n\
    - This routine is similar to sobel_edge_detector(), except instead of finding \n\
      an edge it finds a dark line.  For example, the border between a black piece \n\
      of paper and a white table is an edge, but a curve drawn with a pencil on a \n\
      piece of paper makes a line.  Therefore, the output of this routine is a \n\
      vector field encoded in the horz and vert images, which are returned in a \n\
      tuple where the first element is horz and the second is vert. \n\
 \n\
      The vector obtains a large magnitude when centered on a dark line in an image \n\
      and the direction of the vector is perpendicular to the line.  To be very \n\
      precise, each vector points in the direction of greatest change in second \n\
      derivative and the magnitude of the vector encodes the derivative magnitude \n\
      in that direction.  Moreover, if the second derivative is negative then the \n\
      output vector is zero.  This zeroing if negative gradients causes the output \n\
      to be sensitive only to dark lines surrounded by darker pixels. \n\
 \n\
    - We assume that xx, xy, and yy are the 3 second order gradients of the image \n\
      in question.  You can obtain these gradients using the image_gradients class. \n\
    - The output images will have the same dimensions as the input images. ";
    /*!
        requires
            - xx, xy, and yy all have the same dimensions.
        ensures
            - This routine is similar to sobel_edge_detector(), except instead of finding
              an edge it finds a dark line.  For example, the border between a black piece
              of paper and a white table is an edge, but a curve drawn with a pencil on a
              piece of paper makes a line.  Therefore, the output of this routine is a
              vector field encoded in the horz and vert images, which are returned in a
              tuple where the first element is horz and the second is vert.

              The vector obtains a large magnitude when centered on a dark line in an image
              and the direction of the vector is perpendicular to the line.  To be very
              precise, each vector points in the direction of greatest change in second
              derivative and the magnitude of the vector encodes the derivative magnitude
              in that direction.  Moreover, if the second derivative is negative then the
              output vector is zero.  This zeroing if negative gradients causes the output
              to be sensitive only to dark lines surrounded by darker pixels.

            - We assume that xx, xy, and yy are the 3 second order gradients of the image
              in question.  You can obtain these gradients using the image_gradients class.
            - The output images will have the same dimensions as the input images.
    !*/
    m.def("find_dark_lines",       &py_find_dark_lines,       docs, py::arg("xx"), py::arg("xy"), py::arg("yy"));

    docs =
"requires \n\
    - xx, xy, and yy all have the same dimensions. \n\
ensures \n\
    - This routine finds bright \"keypoints\" in an image.  In general, these are \n\
      bright/white localized blobs.  It does this by computing the determinant of \n\
      the image Hessian at each location and storing this value into the returned \n\
      image if both eigenvalues of the Hessian are negative.  If either eigenvalue \n\
      is positive then the output value for that pixel is 0.  I.e. \n\
        - Let OUT denote the returned image. \n\
        - for all valid r,c: \n\
            - OUT[r][c] == a number >= 0 and larger values indicate the \n\
              presence of a keypoint at this pixel location. \n\
    - We assume that xx, xy, and yy are the 3 second order gradients of the image \n\
      in question.  You can obtain these gradients using the image_gradients class. \n\
    - The output image will have the same dimensions as the input images.";
    /*!
        requires
            - xx, xy, and yy all have the same dimensions.
        ensures
            - This routine finds bright "keypoints" in an image.  In general, these are
              bright/white localized blobs.  It does this by computing the determinant of
              the image Hessian at each location and storing this value into the returned
              image if both eigenvalues of the Hessian are negative.  If either eigenvalue
              is positive then the output value for that pixel is 0.  I.e.
                - Let OUT denote the returned image.
                - for all valid r,c:
                    - OUT[r][c] == a number >= 0 and larger values indicate the
                      presence of a keypoint at this pixel location.
            - We assume that xx, xy, and yy are the 3 second order gradients of the image
              in question.  You can obtain these gradients using the image_gradients class.
            - The output image will have the same dimensions as the input images.
    !*/
    m.def("find_bright_keypoints", &py_find_bright_keypoints, docs, py::arg("xx"), py::arg("xy"), py::arg("yy"));

    docs =
"requires \n\
    - xx, xy, and yy all have the same dimensions. \n\
ensures \n\
    - This routine finds dark \"keypoints\" in an image.  In general, these are \n\
      dark localized blobs.  It does this by computing the determinant of \n\
      the image Hessian at each location and storing this value into the returned \n\
      image if both eigenvalues of the Hessian are negative.  If either eigenvalue \n\
      is negative then the output value for that pixel is 0.  I.e. \n\
        - Let OUT denote the returned image. \n\
        - for all valid r,c: \n\
            - OUT[r][c] == a number >= 0 and larger values indicate the \n\
              presence of a keypoint at this pixel location. \n\
    - We assume that xx, xy, and yy are the 3 second order gradients of the image \n\
      in question.  You can obtain these gradients using the image_gradients class. \n\
    - The output image will have the same dimensions as the input images.";
    /*!
        requires
            - xx, xy, and yy all have the same dimensions.
        ensures
            - This routine finds dark "keypoints" in an image.  In general, these are
              dark localized blobs.  It does this by computing the determinant of
              the image Hessian at each location and storing this value into the returned
              image if both eigenvalues of the Hessian are negative.  If either eigenvalue
              is negative then the output value for that pixel is 0.  I.e.
                - Let OUT denote the returned image.
                - for all valid r,c:
                    - OUT[r][c] == a number >= 0 and larger values indicate the
                      presence of a keypoint at this pixel location.
            - We assume that xx, xy, and yy are the 3 second order gradients of the image
              in question.  You can obtain these gradients using the image_gradients class.
            - The output image will have the same dimensions as the input images.
    !*/
    m.def("find_dark_keypoints",   &py_find_dark_keypoints,   docs, py::arg("xx"), py::arg("xy"), py::arg("yy"));

    docs =
"requires \n\
    - The two input images have the same dimensions. \n\
ensures \n\
    - Returns an image, of the same dimensions as the input.  Each element in this \n\
      image holds the edge strength at that location.  Moreover, edge pixels that are not  \n\
      local maximizers have been set to 0. \n\
    - let edge_strength(r,c) == sqrt(pow(horz[r][c],2) + pow(vert[r][c],2)) \n\
      (i.e. The Euclidean norm of the gradient) \n\
    - let OUT denote the returned image. \n\
    - for all valid r and c: \n\
        - if (edge_strength(r,c) is at a maximum with respect to its 2 neighboring \n\
          pixels along the line indicated by the image gradient vector (horz[r][c],vert[r][c])) then \n\
            - OUT[r][c] == edge_strength(r,c) \n\
        - else \n\
            - OUT[r][c] == 0";
    /*!
        requires
            - The two input images have the same dimensions.
        ensures
            - Returns an image, of the same dimensions as the input.  Each element in this
              image holds the edge strength at that location.  Moreover, edge pixels that are not
              local maximizers have been set to 0.
            - let edge_strength(r,c) == sqrt(pow(horz[r][c],2) + pow(vert[r][c],2))
              (i.e. The Euclidean norm of the gradient)
            - let OUT denote the returned image.
            - for all valid r and c:
                - if (edge_strength(r,c) is at a maximum with respect to its 2 neighboring
                  pixels along the line indicated by the image gradient vector (horz[r][c],vert[r][c])) then
                    - OUT[r][c] == edge_strength(r,c)
                - else
                    - OUT[r][c] == 0
    !*/
    m.def("suppress_non_maximum_edges", &py_suppress_non_maximum_edges, docs, py::arg("horz"), py::arg("vert"));
    m.def("suppress_non_maximum_edges", &py_suppress_non_maximum_edges2,
        "Performs: return suppress_non_maximum_edges(horz_and_vert_gradients[0], horz_and_vert_gradients[1])",
        py::arg("horz_and_vert_gradients"));

    docs =
"requires \n\
    - non_max_suppression_radius >= 0 \n\
ensures \n\
    - Scans the given image and finds all pixels with values >= thresh that are \n\
      also local maximums within their 8-connected neighborhood of the image.  Such \n\
      pixels are collected, sorted in decreasing order of their pixel values, and \n\
      then non-maximum suppression is applied to this list of points using the \n\
      given non_max_suppression_radius.  The final list of peaks is then returned. \n\
 \n\
      Therefore, the returned list, V, will have these properties: \n\
        - len(V) == the number of peaks found in the image. \n\
        - When measured in image coordinates, no elements of V are within \n\
          non_max_suppression_radius distance of each other.  That is, for all valid i!=j \n\
          it is true that length(V[i]-V[j]) > non_max_suppression_radius. \n\
        - For each element of V, that element has the maximum pixel value of all \n\
          pixels in the ball centered on that pixel with radius \n\
          non_max_suppression_radius.";
    /*!
        requires
            - non_max_suppression_radius >= 0
        ensures
            - Scans the given image and finds all pixels with values >= thresh that are
              also local maximums within their 8-connected neighborhood of the image.  Such
              pixels are collected, sorted in decreasing order of their pixel values, and
              then non-maximum suppression is applied to this list of points using the
              given non_max_suppression_radius.  The final list of peaks is then returned.

              Therefore, the returned list, V, will have these properties:
                - len(V) == the number of peaks found in the image.
                - When measured in image coordinates, no elements of V are within
                  non_max_suppression_radius distance of each other.  That is, for all valid i!=j
                  it is true that length(V[i]-V[j]) > non_max_suppression_radius.
                - For each element of V, that element has the maximum pixel value of all
                  pixels in the ball centered on that pixel with radius
                  non_max_suppression_radius.
    !*/
    m.def("find_peaks", &py_find_peaks<float>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<double>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<uint8_t>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<uint16_t>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<uint32_t>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<uint64_t>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<int8_t>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<int16_t>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<int32_t>, py::arg("img"), py::arg("non_max_suppression_radius"), py::arg("thresh"));
    m.def("find_peaks", &py_find_peaks<int64_t>, py::arg("img"), docs, py::arg("non_max_suppression_radius"), py::arg("thresh"));

    m.def("find_peaks", &py_find_peaks2<float>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<double>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<uint8_t>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<uint16_t>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<uint32_t>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<uint64_t>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<int8_t>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<int16_t>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<int32_t>, py::arg("img"), py::arg("non_max_suppression_radius")=0);
    m.def("find_peaks", &py_find_peaks2<int64_t>, py::arg("img"),
        "performs: return find_peaks(img, non_max_suppression_radius, partition_pixels(img))",
        py::arg("non_max_suppression_radius")=0);

    docs =
"Applies the sobel edge detector to the given input image and returns two gradient \n\
images in a tuple.  The first contains the x gradients and the second contains the \n\
y gradients of the image.";
    /*!
         Applies the sobel edge detector to the given input image and returns two gradient
         images in a tuple.  The first contains the x gradients and the second contains the
         y gradients of the image.
    !*/
    m.def("sobel_edge_detector", &py_sobel_edge_detector<uint8_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<uint16_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<uint32_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<uint64_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<int8_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<int16_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<int32_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<int64_t>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<float>, py::arg("img"));
    m.def("sobel_edge_detector", &py_sobel_edge_detector<double>, docs, py::arg("img"));

    docs =
"Applies hysteresis thresholding to img and returns the results.  In particular, \n\
pixels in img with values >= upper_thresh have an output value of 255 and all \n\
others have a value of 0 unless they are >= lower_thresh and are connected to a \n\
pixel with a value >= upper_thresh, in which case they have a value of 255.  Here \n\
pixels are connected if there is a path between them composed of pixels that would \n\
receive an output of 255.";
    /*!
        Applies hysteresis thresholding to img and returns the results.  In particular,
        pixels in img with values >= upper_thresh have an output value of 255 and all
        others have a value of 0 unless they are >= lower_thresh and are connected to a
        pixel with a value >= upper_thresh, in which case they have a value of 255.  Here
        pixels are connected if there is a path between them composed of pixels that would
        receive an output of 255.
    !*/
    m.def("hysteresis_threshold", &py_hysteresis_threshold<uint8_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<uint16_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<uint32_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<uint64_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<int8_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<int16_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<int32_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<int64_t>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<float>, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold<double>, docs, py::arg("img"), py::arg("lower_thresh"), py::arg("upper_thresh"));

    docs =
"performs: return hysteresis_threshold(img, t1, t2) where the thresholds \n\
are first obtained by calling [t1, t2]=partition_pixels(img).";
    /*!
        performs: return hysteresis_threshold(img, t1, t2) where the thresholds
        are first obtained by calling [t1, t2]=partition_pixels(img).
    !*/
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<uint8_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<uint16_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<uint32_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<uint64_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<int8_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<int16_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<int32_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<int64_t>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<float>, py::arg("img"));
    m.def("hysteresis_threshold", &py_hysteresis_threshold2<double>, docs, py::arg("img"));
}