ambisonics.h

Go to the documentation of this file.

/*
 ambisonics.h
 Spatial Audio Library (SAL)
 Copyright (c) 2012, Enzo De Sena
 All rights reserved.
 
 This include contains definition of classes and functions
 related to higer-order ambisonics.
 
 Authors: Enzo De Sena, enzodesena@gmail.com
 
 */

#ifndef SAL_HOA_H
#define SAL_HOA_H


#include "microphone.h"
#include "point.h"
#include "decoder.h"
#include "microphonearray.h"
#include "salconstants.h"
#include "iirfilter.h"

namespace sal {

enum HoaNormalisation {
  sqrt2,
  N3d,
  Sn3d,
  Fuma
};


class AmbisonicsMic : public Microphone {
public:
  AmbisonicsMic(const mcl::Point& position, mcl::Quaternion orientation,
                Int order, HoaNormalisation normalisation = HoaNormalisation::sqrt2,
                HoaOrdering ordering = HoaOrdering::Acn) :
          Microphone(position, orientation),
          order_(order), normalisation_convention_(normalisation),
          ordering_convention_(ordering) {}
  
  bool IsCoincident() const noexcept { return true; }
  
  Int num_channels() const noexcept {
    return HoaBuffer::GetNumChannels(order_);
  }
  
  static std::vector<mcl::Real> HorizontalEncoding(Int order, Angle theta);
  
  static bool Test();
  virtual void AddPlaneWaveRelative(const Sample* input_data,
                                    const Int num_samples,
                                    const mcl::Point& point,
                                    const Int wave_id,
                                    Buffer& output_buffer) noexcept;
  
  
private:
  
  const Int order_;
  HoaNormalisation normalisation_convention_;
  HoaOrdering ordering_convention_;
};

  
class AmbisonicsHorizDec : public Decoder {
public:
  AmbisonicsHorizDec(const Int order,
                     const bool energy_decoding,
                     const Time cut_off_frequency,
                     const std::vector<Angle>& loudspeaker_angles,
                     const bool near_field_correction,
                     const Length loudspeakers_distance,
                     const Time sampling_frequency,
                     const Speed sound_speed,
                     const HoaOrdering ordering_convention = HoaOrdering::Acn);
  
  virtual void Decode(const Buffer& input_buffer,
                      Buffer& output_buffer);
  
  
  static bool Test();

  virtual ~AmbisonicsHorizDec() {}
  
private:
  
  static mcl::Matrix<Sample>
  ModeMatchingDec(Int order, const std::vector<Angle>& loudspeaker_angles);
  
  static mcl::Matrix<Sample>
  MaxEnergyDec(Int order, const std::vector<Angle>& loudspeaker_angles);
  
  static Sample MaxEnergyDecWeight(Int index, Int order) {
    return (Sample) cos(((Angle) index)*PI/(2.0*((Angle) order)+2.0));
  }
  
  std::vector<Sample> GetFrame(const Int order, const Int sample_id,
                               const Buffer& buffer);
  
  static mcl::IirFilter NFCFilter(const Int order,
                                  const Length loudspeaker_distance,
                                  const Time sampling_frequency,
                                  const Length sound_speed);

  
  static mcl::IirFilter CrossoverFilterLow(const Time cut_off_frequency,
                                           const Time sampling_frequency);
  static mcl::IirFilter CrossoverFilterHigh(const Time cut_off_frequency,
                                            const Time sampling_frequency);
  
  std::vector<Angle> loudspeaker_angles_;
  Int num_loudspeakers_;
  bool near_field_correction_;
  Length loudspeakers_distance_;
  bool energy_decoding_;
  // Ambisonics order
  Int order_;
  HoaOrdering ordering_convention_;
  
  // One filter per component
  std::vector<mcl::IirFilter> nfc_filters_;
  // One filter per loudspeaker
  std::vector<mcl::IirFilter> crossover_filters_high_;
  std::vector<mcl::IirFilter> crossover_filters_low_;
  
  // Cache the decoding matrix (mode-matching) for performance purposes.
  mcl::Matrix<Sample> mode_matching_matrix_;
  
  // Cache the decoding matrix (maximum energy) for performance purposes.
  mcl::Matrix<Sample> max_energy_matrix_;
  
  Time sampling_frequency_;
};
  
  
} // namespace sal

#endif