docstr: Start the optimization process.
  
  Parameters
  ----------
  static : 2D or 3D array
      the image to be used as reference during optimization.
  moving : 2D or 3D array
      the image to be used as "moving" during optimization. It is
      necessary to pre-align the moving image to ensure its domain
      lies inside the domain of the deformation fields. This is assumed
      to be accomplished by "pre-aligning" the moving image towards the
      static using an affine transformation given by the
      'starting_affine' matrix
  transform : instance of Transform
      the transformation with respect to whose parameters the gradient
      must be computed
  params0 : array, shape (n,)
      parameters from which to start the optimization. If None, the
      optimization will start at the identity transform. n is the
      number of parameters of the specified transformation.
  static_grid2world : array, shape (dim+1, dim+1), optional
      the voxel-to-space transformation associated with the static
      image. The default is None, implying the transform is the
      identity.
  moving_grid2world : array, shape (dim+1, dim+1), optional
      the voxel-to-space transformation associated with the moving
      image. The default is None, implying the transform is the
      identity.
  starting_affine : string, or matrix, or None, optional
      If string:
          'mass': align centers of gravity
          'voxel-origin': align physical coordinates of voxel (0,0,0)
          'centers': align physical coordinates of central voxels
      If matrix:
          array, shape (dim+1, dim+1).
      If None:
          Start from identity.
      The default is None.
  ret_metric : boolean, optional
      if True, it returns the parameters for measuring the
      similarity between the images (default 'False').
      The metric containing optimal parameters and
      the distance between the images.
  static_mask : array, shape (S, R, C) or (R, C), optional
      static image mask that defines which pixels in the static image
      are used to calculate the mutual information.
  moving_mask : array, shape (S', R', C') or (R', C'), optional
      moving image mask that defines which pixels in the moving image
      are used to calculate the mutual information.
  
  Returns
  -------
  affine_map : instance of AffineMap
      the affine resulting affine transformation
  xopt : optimal parameters
      the optimal parameters (translation, rotation shear etc.)
  fopt : Similarity metric
      the value of the function at the optimal parameters.
docstr_tok: ["Start","the","optimization","process",".","Parameters","--","--","--","--","--","static",":","2D","or","3D","array","the","image","to","be","used","as","reference","during","optimization",".","moving",":","2D","or","3D","array","the","image","to","be","used","as","``","moving","''","during","optimization",".","It","is","necessary","to","pre-align","the","moving","image","to","ensure","its","domain","lies","inside","the","domain","of","the","deformation","fields",".","This","is","assumed","to","be","accomplished","by","``","pre-aligning","''","the","moving","image","towards","the","static","using","an","affine","transformation","given","by","the","'starting_affine","'","matrix","transform",":","instance","of","Transform","the","transformation","with","respect","to","whose","parameters","the","gradient","must","be","computed","params0",":","array",",","shape","(","n",",",")","parameters","from","which","to","start","the","optimization",".","If","None",",","the","optimization","will","start","at","the","identity","transform",".","n","is","the","number","of","parameters","of","the","specified","transformation",".","static_grid2world",":","array",",","shape","(","dim+1",",","dim+1",")",",","optional","the","voxel-to-space","transformation","associated","with","the","static","image",".","The","default","is","None",",","implying","the","transform","is","the","identity",".","moving_grid2world",":","array",",","shape","(","dim+1",",","dim+1",")",",","optional","the","voxel-to-space","transformation","associated","with","the","moving","image",".","The","default","is","None",",","implying","the","transform","is","the","identity",".","starting_affine",":","string",",","or","matrix",",","or","None",",","optional","If","string",":","'mass","'",":","align","centers","of","gravity","'voxel-origin","'",":","align","physical","coordinates","of","voxel","(","0,0,0",")","'centers","'",":","align","physical","coordinates","of","central","voxels","If","matrix",":","array",",","shape","(","dim+1",",","dim+1",")",".","If","None",":","Start","from","identity",".","The","default","is","None",".","ret_metric",":","boolean",",","optional","if","True",",","it","returns","the","parameters","for","measuring","the","similarity","between","the","images","(","default","'False","'",")",".","The","metric","containing","optimal","parameters","and","the","distance","between","the","images",".","static_mask",":","array",",","shape","(","S",",","R",",","C",")","or","(","R",",","C",")",",","optional","static","image","mask","that","defines","which","pixels","in","the","static","image","are","used","to","calculate","the","mutual","information",".","moving_mask",":","array",",","shape","(","S","'",",","R","'",",","C","'",")","or","(","R","'",",","C","'",")",",","optional","moving","image","mask","that","defines","which","pixels","in","the","moving","image","are","used","to","calculate","the","mutual","information",".","Returns","--","--","--","-","affine_map",":","instance","of","AffineMap","the","affine","resulting","affine","transformation","xopt",":","optimal","parameters","the","optimal","parameters","(","translation",",","rotation","shear","etc",".",")","fopt",":","Similarity","metric","the","value","of","the","function","at","the","optimal","parameters","."]
code: def optimize(
      self,
      static,
      moving,
      transform,
      params0,
      static_grid2world=None,
      moving_grid2world=None,
      starting_affine=None,
      ret_metric=False,
      static_mask=None,
      moving_mask=None,
  ):
      r"""Start the optimization process.
  
      Parameters
      ----------
      static : 2D or 3D array
          the image to be used as reference during optimization.
      moving : 2D or 3D array
          the image to be used as "moving" during optimization. It is
          necessary to pre-align the moving image to ensure its domain
          lies inside the domain of the deformation fields. This is assumed
          to be accomplished by "pre-aligning" the moving image towards the
          static using an affine transformation given by the
          'starting_affine' matrix
      transform : instance of Transform
          the transformation with respect to whose parameters the gradient
          must be computed
      params0 : array, shape (n,)
          parameters from which to start the optimization. If None, the
          optimization will start at the identity transform. n is the
          number of parameters of the specified transformation.
      static_grid2world : array, shape (dim+1, dim+1), optional
          the voxel-to-space transformation associated with the static
          image. The default is None, implying the transform is the
          identity.
      moving_grid2world : array, shape (dim+1, dim+1), optional
          the voxel-to-space transformation associated with the moving
          image. The default is None, implying the transform is the
          identity.
      starting_affine : string, or matrix, or None, optional
          If string:
              'mass': align centers of gravity
              'voxel-origin': align physical coordinates of voxel (0,0,0)
              'centers': align physical coordinates of central voxels
          If matrix:
              array, shape (dim+1, dim+1).
          If None:
              Start from identity.
          The default is None.
      ret_metric : boolean, optional
          if True, it returns the parameters for measuring the
          similarity between the images (default 'False').
          The metric containing optimal parameters and
          the distance between the images.
      static_mask : array, shape (S, R, C) or (R, C), optional
          static image mask that defines which pixels in the static image
          are used to calculate the mutual information.
      moving_mask : array, shape (S', R', C') or (R', C'), optional
          moving image mask that defines which pixels in the moving image
          are used to calculate the mutual information.
  
      Returns
      -------
      affine_map : instance of AffineMap
          the affine resulting affine transformation
      xopt : optimal parameters
          the optimal parameters (translation, rotation shear etc.)
      fopt : Similarity metric
          the value of the function at the optimal parameters.
  
      """
      self._init_optimizer(
          static,
          moving,
          transform,
          params0,
          static_grid2world,
          moving_grid2world,
          starting_affine,
          static_mask,
          moving_mask,
      )
      del starting_affine  # Now we must refer to self.starting_affine
      del static_mask  # Now we must refer to self.static_mask
      del moving_mask  # Now we must refer to self.moving_mask
  
      # Multi-resolution iterations
      original_static_shape = self.static_ss.get_image(0).shape
      original_static_grid2world = self.static_ss.get_affine(0)
      original_moving_shape = self.moving_ss.get_image(0).shape
      original_moving_grid2world = self.moving_ss.get_affine(0)
      affine_map = AffineMap(
          None,
          original_static_shape,
          original_static_grid2world,
          original_moving_shape,
          original_moving_grid2world,
      )
  
      for level in range(self.levels - 1, -1, -1):
          self.current_level = level
          max_iter = self.level_iters[-1 - level]
          if self.verbosity >= VerbosityLevels.STATUS:
              print(
                  "Optimizing level %d [max iter: %d]"
                  % (level, max_iter)
              )
  
          # Resample the smooth static image to the shape of this level
          smooth_static = self.static_ss.get_image(level)
          current_static_shape = self.static_ss.get_domain_shape(level)
          current_static_grid2world = self.static_ss.get_affine(level)
          current_affine_map = AffineMap(
              None,
              current_static_shape,
              current_static_grid2world,
              original_static_shape,
              original_static_grid2world,
          )
          current_static = current_affine_map.transform(smooth_static)
          current_static_mask = None
          if self.static_mask is not None:
              current_static_mask = current_affine_map.transform(
                  self.static_mask, interpolation="nearest"
              ).astype(np.int32)
  
          # The moving image is full resolution
          current_moving_grid2world = original_moving_grid2world
  
          current_moving = self.moving_ss.get_image(level)
  
          # Prepare the metric for iterations at this resolution
          self.metric.setup(
              transform,
              current_static,
              current_moving,
              current_static_grid2world,
              current_moving_grid2world,
              self.starting_affine,
              current_static_mask,
              self.moving_mask,
          )
  
          # Optimize this level
          if self.options is None:
              self.options = {"gtol": 1e-4, "disp": False}
  
          if self.method == "L-BFGS-B":
              self.options["maxfun"] = max_iter
          else:
              self.options["maxiter"] = max_iter
  
          opt = Optimizer(
              self.metric.distance_and_gradient,
              self.params0,
              method=self.method,
              jac=True,
              options=self.options,
          )
          params = opt.xopt
  
          # Update starting_affine matrix with optimal parameters
          T = self.transform.param_to_matrix(params)
          self.starting_affine = T.dot(self.starting_affine)
  
          # Start next iteration at identity
          self.params0 = self.transform.get_identity_parameters()
  
      affine_map.set_affine(self.starting_affine)
      if ret_metric:
          return affine_map, opt.xopt, opt.fopt
      return affine_map
  
imports: from warnings import warn
  import numpy
  import numpy.linalg
  import scipy.ndimage
  from dipy.core.optimize import Optimizer
  from dipy.core.interpolation import interpolate_scalar_2d, interpolate_scalar_3d
  from dipy.align import vector_fields
  from dipy.align import VerbosityLevels
  from dipy.align.parzenhist import ParzenJointHistogram, sample_domain_regular, compute_parzen_mi
  from dipy.align.imwarp import get_direction_and_spacings, ScaleSpace
  from dipy.align.scalespace import IsotropicScaleSpace
  from dipy.utils.deprecator import deprecated_params
label_desc: Use image node_id 3 for calling the AffineRegistration obj's underlying member method code with example usage: obj.optimize(static, moving, transform, params0, static_grid2world, moving_grid2world, starting_affine, ret_metric, static_mask, moving_mask) and returns: affine_map, affine_map,  opt,  opt