README
¶
hz.tools/sdr/fft
This package contains helpers for implementing and using FFTs within the hz.tools ecosystem. There are many ways of doing an FFT, from OpenCL (clFFT), to fftw, to a pure-go FFT implementation you write up for fun.
In an effort to not tie this library to a single FFT library, this defines a generic interface to use FFTs within the codebase, and user code can pass an FFT backend that makes sense for where it is.
Additionally, this contains helpers for working with the FFT output, such as getting frequency widths, or bin indexes by frequency.
Documentation
¶
Overview ¶
Package fft contains a common interface to perform FFTs between frequency and time-Series complex data.
Index ¶
- Variables
- func BinBandwidth(frequencyLen int, sampleRate uint) rf.Hz
- func BinByFreq(frequencyLen int, sampleRate uint, order Order, freq rf.Hz) (int, error)
- func BinsByRange(frequencyLen int, sampleRate uint, order Order, rng rf.Range) ([]int, error)
- func Convolve(planner Planner, dst sdr.Samples, iq1 sdr.Samples, iq2 sdr.Samples) (func() error, error)
- func ConvolveFreq(planner Planner, dst sdr.Samples, src sdr.Samples, freq []complex64) (func() error, error)
- func ConvolveOnce(planner Planner, dst sdr.Samples, iq1 sdr.Samples, iq2 sdr.Samples) error
- func CrossCorrelate(planner Planner, dst sdr.Samples, iq1 sdr.Samples, iq2 sdr.Samples) (func() error, error)
- func FreqByBin(frequencyLen int, sampleRate uint, order Order, bin int) (rf.Hz, error)
- func Nyquest(sampleRate uint) rf.Hz
- func Shift(frequency []complex64) error
- func TransformOnce(planner Planner, iq sdr.SamplesC64, frequency []complex64, direction Direction) error
- type Direction
- type FrequencySlice
- func (r FrequencySlice) BinBandwidth() rf.Hz
- func (r FrequencySlice) BinByFreq(freq rf.Hz) (int, error)
- func (r FrequencySlice) BinsByRange(rng rf.Range) ([]int, error)
- func (r FrequencySlice) FreqByBin(bin int) (rf.Hz, error)
- func (r FrequencySlice) Nyquest() rf.Hz
- func (r FrequencySlice) Shift() (FrequencySlice, error)
- type Order
- type Plan
- type Planner
Constants ¶
This section is empty.
Variables ¶
var ( // ErrFrequencyOutOfSamplingRange is returned if the target frequency is too // far outside the sampling rate of the underlying sample rate. ErrFrequencyOutOfSamplingRange = fmt.Errorf("fft: target frequency is out of sampling rate") )
Functions ¶
func BinBandwidth ¶
BinBandwidth will return the bandwidth represented by a provided bin.
func BinsByRange ¶
BinsByRange will return the bins that contain frequencies bounded by the range 'rng'.
func Convolve ¶
func Convolve( planner Planner, dst sdr.Samples, iq1 sdr.Samples, iq2 sdr.Samples, ) (func() error, error)
Convolve will plan a convolution of two time-series IQ samples, returning a function to repeatedly convolve the two provided IQ buffers. The output of the convolution will be written to the dst Samples. The dst argument may safely be one of iq1 or iq2.
Under the hood this will use the provided FFT Planner to multiply the samples in the frequency domain, which winds up a lot faster than having to perform the convolution in the time domain.
func ConvolveFreq ¶
func ConvolveFreq( planner Planner, dst sdr.Samples, src sdr.Samples, freq []complex64, ) (func() error, error)
ConvolveFreq will plan a convolution of frequency-domain complex numbers against time-series iq data in the frequency domain, returning a function to repeatedly convolve the two provided IQ buffers. The output of the convolution will be written to the dst Samples. The dst argument may safely be one of iq1 or iq2.
Under the hood this will use the provided FFT Planner to multiply the samples in the frequency domain, which winds up a lot faster than having to perform the convolution in the time domain.
func ConvolveOnce ¶
ConvolveOnce will perform a one-off convolution of two time series iq streams in the frequency domain, writing the results to the dst samples. The dst argument may safely be one of iq1 or iq2.
If this function is invoked multiple times, consider using the Convolve function to plan the convolution, to save on setup time from the fft planner.
func CrossCorrelate ¶
func CrossCorrelate( planner Planner, dst sdr.Samples, iq1 sdr.Samples, iq2 sdr.Samples, ) (func() error, error)
CrossCorrelate will plan a cross correlation in the frequency domain between two iq buffers to determine what offset (if any) contain a correlation with the exemplar.
func FreqByBin ¶
FreqByBin will return the center frequency of the provided fft bin, provided with information on the fft size, sample rate and bin layout.
func Nyquest ¶
Nyquest will return the Nyquest frequency of the IQ stream with the provided Sample Rate.
func Shift ¶
Shift will shift a FFT window from the native 0-index being 0 hz, to 0hz being the center of the buffer.
func TransformOnce ¶
func TransformOnce( planner Planner, iq sdr.SamplesC64, frequency []complex64, direction Direction, ) error
TransformOnce will perform either a time-to-frequency or frequency-to-time domain transformation once. If this is called multiple times, significant overhead can be reduced by using the Planner interface.
Types ¶
type Direction ¶
type Direction bool
Direction indicates if this is either a Forward or Backward FFT.
type FrequencySlice ¶
type FrequencySlice struct {
// Frequency is a slice of frequency space.
Frequency []complex64
// SampleRate is the number of readings per second in the time domain
// used to generate the data input into the FFT.
SampleRate uint
// Order is what order bins are in memory -- either ZeroFirst or
// NegativeFirst. More orders may be added in future, so a switch ought
// to be used, and default to returning an error case, even if this
// is not possible given the current type.
Order Order
}
FrequencySlice is the common struct we can use to make sense of the common data we need to pass around.
func NewFrequencySlice ¶
func NewFrequencySlice(frequency []complex64, sampleRate uint, order Order) FrequencySlice
NewFrequencySlice will create a new fft.FrequencySlice - which is a struct that represents the results of a forward FFT in the frequency domain, *not* any time-domain samples. Those should be of type sdr.SamplesC64.
func (FrequencySlice) BinBandwidth ¶
func (r FrequencySlice) BinBandwidth() rf.Hz
BinBandwidth is the amount frequency each bin represents in a fft slice.
func (FrequencySlice) BinByFreq ¶
func (r FrequencySlice) BinByFreq(freq rf.Hz) (int, error)
BinByFreq will return the bin index by a provided frequency.
func (FrequencySlice) BinsByRange ¶
func (r FrequencySlice) BinsByRange(rng rf.Range) ([]int, error)
BinsByRange will return the bins representing the range provided.
func (FrequencySlice) FreqByBin ¶
func (r FrequencySlice) FreqByBin(bin int) (rf.Hz, error)
FreqByBin will return the center of the bin represented by an offset.
func (FrequencySlice) Nyquest ¶
func (r FrequencySlice) Nyquest() rf.Hz
Nyquest is half the sampling rate.
func (FrequencySlice) Shift ¶
func (r FrequencySlice) Shift() (FrequencySlice, error)
Shift will go from ZeroFirst to negativeFirst or vice versa.
type Order ¶
type Order bool
Order specifies what order the fft slice is in.
var ( // ZeroFirst indicates that the fft data starts with 0, then increases // through frequencies to the positive nyquest frequency, then starts // at the negative nyquest frequency, back to 0. ZeroFirst Order = false // NegativeFirst represents what humans understand as an fft, where it // starts at the negative nyquest frequency through to the positive // nyquest frequency, with 0hz in the center. NegativeFirst Order = true )
Source Files