view trunk/carfac/sai.h @ 695:2e3672df5698

Simple integration test between CARFAC and SAI.

The interface between the two classes is pretty clunky because of the
way CARFACOutput stores things.  We should work on this, probably by
rotating the outer two dimensions of CARFACOutput (i.e. store outputs
in containers with sizes n_ears x n_samples x n_channels instead of
n_samples x n_ears x n_channels).

// Copyright 2013, Google, Inc.
// Author: Ron Weiss <[e-mail]>
//
// This C++ file is part of an implementation of Lyon's cochlear model:
// "Cascade of Asymmetric Resonators with Fast-Acting Compression"
// to supplement Lyon's upcoming book "Human and Machine Hearing"
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef CARFAC_SAI_H_
#define CARFAC_SAI_H_

#include <vector>

#include "common.h"

// Design parameters for a single SAI.
struct SAIParams {
  // Number of channels (height) of the SAI.
  int n_ch;

  // TODO(ronw): Consider parameterizing this as past_lags and
  // future_lags, with width == past_lags + 1 + future_lags.
  //
  // Total width (i.e. number of lag samples) of the SAI.
  int width;
  // Number of lag samples that should come from the future.
  int future_lags;
  // Number of windows (triggers) to consider during each SAI frame.
  int n_window_pos;

  // TODO(ronw): more carefully define terms "window" and "frame"

  // Size of the window to compute.
  int window_width;

  FPType channel_smoothing_scale;
};

class SAI {
 public:
  explicit SAI(const SAIParams& params);

  // Reinitialize using the specified parameters.
  void Redesign(const SAIParams& params);

  // Reset the internal state.
  void Reset();

  // Fills output_frame with a params_.n_ch by params_.width SAI frame
  // computed from the given input frames.
  //
  // The input should have dimensionality of params_.window_width by
  // params_.n_ch.  Inputs containing too few frames are zero-padded.
  // FIXME: ArrayXX input type would be less awkward.
  void RunSegment(const std::vector<ArrayX>& input,
                  ArrayXX* output_output_frame);

 private:
  // Processes successive windows within input_buffer, choose trigger
  // points, and blend each window into output_buffer.
  void StabilizeSegment(const ArrayXX& input_buffer,
                        ArrayXX* output_buffer) const;

  SAIParams params_;
  // Window function to apply before selecting a trigger point.
  // Size: params_.window_width.
  ArrayX window_;
  // Buffer to store a large enough window of input frames to compute
  // a full SAI frame.  Size: params_.n_ch by params_.buffer_width.
  ArrayXX input_buffer_;
  // Output frame buffer.  Size: params_.n_ch by params_.width.
  ArrayXX output_buffer_;
};

#endif  // CARFAC_SAI_H_