#ifndef pz_opt_matrix_H
#define pz_opt_matrix_H

/* Procedures for optimizing a transformation matrix */
/* Last edited on 2008-02-08 13:46:43 by stolfi */

#include <r4x4.h>

#include <pz_types.h>

typedef double pz_matrix_func_t (r4x4_t *m); 
  /* Type of a function that returns a badness measure for the 
    transfomation matrix {m}. */

void pz_opt_matrix_find
  ( pz_matrix_func_t func,  /* Function to optimize. */
    double scaleX,          /* Scale X length for translation. */
    double scaleY,          /* Scale Y length for translation. */
    unsigned maxEvals,      /* Maximum number of "func" calls. */ 
    unsigned *nEvals,       /* OUT: Total number of "func" calls performed. */
    r4x4_t *m,              /* IN: initial guess, OUT: optimized matrix. */
    double *f,              /* OUT: "func(m)". */
    char *plotName,         /* Plot file for "func" (minus extension); or empty. */
  );
  /* Returns a rotation/translation matrix "m" that minimizes "func".
    
    The "scaleX" and "scaleY" parameters are the unit of translation
    in each axis. They should be chosen so that translation by
    "(eps*scaleX,0)" or "(0,eps*scaleY)" away from the optimum has
    roughly the same effect on "func" as a rotation by "eps" radians
    away from the optimum.
    
    If "plotName" is not empty, the procedure writes to "plotName & \".plt\""
    a graph of "func(m)", where "m" varies along a path from the 
    initial matrix "m" to the returned optimum, and then beyond it.
    
    Always performs at least one evaluation, even if "maxEvals == 0". */

#endif