content: /**
   * Copyright 2006 DFKI GmbH.
   * All Rights Reserved.  Use is subject to license terms.
   * <p/>
   * This file is part of MARY TTS.
   * <p/>
   * MARY TTS is free software: you can redistribute it and/or modify
   * it under the terms of the GNU Lesser General Public License as published by
   * the Free Software Foundation, version 3 of the License.
   * <p/>
   * This program is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU Lesser General Public License for more details.
   * <p/>
   * You should have received a copy of the GNU Lesser General Public License
   * along with this program.  If not, see <http://www.gnu.org/licenses/>.
   */
  package marytts.unitselection.select;
  
  import java.io.IOException;
  import java.io.InputStream;
  
  import marytts.exceptions.MaryConfigurationException;
  import marytts.features.FeatureDefinition;
  import marytts.features.FeatureProcessorManager;
  import marytts.features.FeatureVector;
  import marytts.unitselection.data.FeatureFileReader;
  import marytts.unitselection.data.Unit;
  
  
  /**
   * A target cost function for evaluating the goodness-of-fit of
   * a given unit for a given target.
   *
   * @author Marc Schr&ouml;der
   */
  public interface TargetCostFunction {
      /**
       * Initialise the data needed to do a target cost computation.
       *
       * @param featureFileName name of a file containing the unit features
       * @param weightsStream   an optional weights file -- if non-null, contains
       *                        feature weights that override the ones present in the feature file.
       * @param featProc        a feature processor manager which can provide feature processors
       *                        to compute the features for a target at run time
       * @throws IOException
       * @throws MaryConfigurationException if a configuration problem is detected while loading the data
       */
      void load(String featureFileName, InputStream weightsStream,
                FeatureProcessorManager featProc) throws IOException, MaryConfigurationException;
  
      /**
       * Initialise the data needed to do a target cost computation.
       *
       * @param featureFileReader a reader for the file containing the unit features
       * @param weightsFile       an optional weights file -- if non-null, contains
       *                          feature weights that override the ones present in the feature file.
       * @param featProc          a feature processor manager which can provide feature processors
       *                          to compute the features for a target at run time
       * @throws IOException
       */
      void load(FeatureFileReader featureFileReader, InputStream weightsStream,
                FeatureProcessorManager featProc) throws IOException;
  
      /**
       * Compute the goodness-of-fit of a given unit for a given target.
       *
       * @param target
       * @param unit
       * @return a non-negative number; smaller values mean better fit, i.e. smaller cost.
       */
      double cost(Target target, Unit unit);
  
      /**
       * Compute the features for a given target, and store them in the target.
       *
       * @param target the target for which to compute the features
       * @see Target#getFeatureVector()
       */
      void computeTargetFeatures(Target target);
  
      /**
       * Provide access to the Feature Definition used.
       *
       * @return the feature definition object.
       */
      FeatureDefinition getFeatureDefinition();
  
      /**
       * Get the string representation of the feature value associated with
       * the given unit
       *
       * @param unit        the unit whose feature value is requested
       * @param featureName name of the feature requested
       * @return a string representation of the feature value
       * @throws IllegalArgumentException if featureName is not a known feature
       */
      String getFeature(Unit unit, String featureName);
  
      /**
       * Get the target cost feature vector for the given unit.
       *
       * @param unit
       * @return
       */
      FeatureVector getFeatureVector(Unit unit);
  
      /**
       * Get all feature vectors. This is useful for more efficient access.
       *
       * @return the full array of feature vectors, or null if this method is not supported.
       */
      FeatureVector[] getFeatureVectors();
  
  }
  
  