;*************************************************************************
|
; OM-SoX, (c) 2011-2025 Marlon Schumacher (CIRMMT/McGill, HfM Karlsruhe) *
|
; http://sourceforge.net/projects/omsox/ *
|
; *
|
; Multichannel Audio Manipulation and Functional Batch Processing. *
|
; DSP based on SoX - (c) C.Bagwell and Contributors *
|
; http://sox.sourceforge.net/ *
|
;*************************************************************************
|
;
|
;This program is free software; you can redistribute it and/or
|
;modify it under the terms of the GNU General Public License
|
;as published by the Free Software Foundation; either version 2
|
;of the License, or (at your option) any later version.
|
;
|
;See file LICENSE for further informations on licensing terms.
|
;
|
;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 General Public License for more details.
|
;
|
;You should have received a copy of the GNU General Public License
|
;along with this program; if not, write to the Free Software
|
;Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,10 USA.
|
|
;Authors:
|
; A. Nguyen, 2025
|
; M. Schumacher, 2025
|
|
|
(in-package :om)
|
|
;;; SOX-HOAENCODE ========================
|
|
; Utility functions
|
|
(defun flatten (structure)
|
(cond
|
((null structure)
|
nil)
|
((atom structure)
|
(list structure))
|
(t
|
(mapcan #'flatten structure))
|
)
|
)
|
|
(defun sox-hoaencode-deg-to-rad (x)
|
(* (/ x 180) pi)
|
)
|
|
(defun sox-hoaencode-double-to-float (lst)
|
(mapcar
|
(lambda (x) (float x 0.0S0))
|
lst
|
)
|
)
|
|
; ### Ambisonics Formulas ###
|
|
(defun sox-hoaencode-sn3d-factor (order degree)
|
"This is a placeholder for documentation"
|
(ecase order
|
(0 1)
|
(1 1)
|
(2
|
(ecase (abs degree)
|
(0 1)
|
(1 (/ (sqrt 3) 3))
|
(2 (/ (sqrt 3) 6))
|
))
|
(3
|
(ecase (abs degree)
|
(0 1)
|
(1 (/ (sqrt 6) 6))
|
(2 (/ (sqrt 15) 30))
|
(3 (/ (sqrt 10) 60))
|
)
|
)
|
(4
|
(ecase (abs degree)
|
(0 1)
|
(1 (/ (sqrt 10) 10))
|
(2 (/ (sqrt 5) 30))
|
(3 (/ (sqrt 70) 420))
|
(4 (/ (sqrt 35) 840))
|
)
|
)
|
(5
|
(ecase (abs degree)
|
(0 1)
|
(1 (/ (sqrt 15) 15))
|
(2 (/ (sqrt 105) 210))
|
(3 (/ (sqrt 70) 840))
|
(4 (/ (sqrt 35) 2520))
|
(5 (/ (sqrt 14) 5040))
|
)
|
)
|
(6
|
(ecase (abs degree)
|
(0 1)
|
(1 (/ (sqrt 21) 21))
|
(2 (/ (sqrt 210) 420))
|
(3 (/ (sqrt 210) 2520))
|
(4 (/ (sqrt 7) 2520))
|
(5 (/ (sqrt 154) 55440))
|
(6 (/ (sqrt 462) 332640))
|
)
|
)
|
(7
|
(ecase (abs degree)
|
(0 1)
|
(1 (/ (sqrt 7) 14))
|
(2 (/ (sqrt 42) 252))
|
(3 (/ (sqrt 21) 1260))
|
(4 (/ (sqrt 231) 27720))
|
(5 (/ (sqrt 231) 166320))
|
(6 (/ (sqrt 6006) 4324320))
|
(7 (/ (sqrt 429) 4324320))
|
)
|
)
|
)
|
)
|
|
(defun sox-hoaencode-azimuth-factor (degree theta_deg)
|
"This is a placeholder for documentation"
|
(let*
|
(
|
(theta (sox-hoaencode-deg-to-rad theta_deg))
|
)
|
(if (< degree 0)
|
(sin (* (abs degree) theta))
|
(cos (* (abs degree) theta))
|
)
|
)
|
)
|
|
(defun sox-hoaencode-elevation-factor (order degree phi_deg)
|
"This is a placeholder for documentation"
|
(let*
|
(
|
(phi (sox-hoaencode-deg-to-rad phi_deg))
|
)
|
(ecase order
|
(0 1)
|
(1
|
(ecase (abs degree)
|
(0 (sin phi))
|
(1 (cos phi))
|
))
|
(2
|
(ecase (abs degree)
|
(0 (- (/ (* 3 (expt (sin phi) 2)) 2) (/ 1 2)))
|
(1 (/ (* 3 (* (sin phi) 2)) 2))
|
(2 (* 3 (expt (cos phi) 2)))
|
))
|
(3
|
(ecase (abs degree)
|
(0 (/ (* (sin phi) (- (* 5 (expt (sin phi) 2)) 3)) 2))
|
(1 (- (* 6 (cos phi)) (/ (* 15 (expt (cos phi) 3)) 2)))
|
(2 (* -15 (sin phi) (- (expt (sin phi) 2) 1)))
|
(3 (* 15 (expt (cos phi) 3)))
|
))
|
(4
|
(ecase (abs degree)
|
(0 (+ (/ (* 35 (expt (cos phi) 4)) 8) (- (* 5 (expt (cos phi) 2))) 1))
|
(1 (- (/ (* (sin (* 2 phi)) (- (/ (* 35 (expt (cos phi) 2)) 2) 10)) 2)))
|
(2 (- (/ (* (* 15 (expt (cos phi) 2)) (- (* 7 (expt (cos phi) 2)) 6)) 2)))
|
(3 (* 105 (expt (cos phi) 3) (sin phi) ))
|
(4 (* 105 (expt (cos phi) 4)))
|
))
|
(5
|
(ecase (abs degree)
|
(0 (/ (* (sin phi) (+ (- (* 63 (expt (sin phi) 4)) (* 70 (expt (sin phi) 2))) 15)) 8))
|
(1 (/ (* 15 (sin phi) (+ (- (* 21 (expt (cos phi) 4)) (* 28 (expt (cos phi) 2))) 8)) 8))
|
(2 (- (/ (* 105 (sin phi) (+ (- (* 3 (expt (sin phi) 4)) (* 4 (expt (sin phi) 2))) 1)) 2)))
|
(3 (- (/ (* 105 (expt (cos phi) 3) (- (* 9 (expt (cos phi) 2)) 8)) 2)))
|
(4 (* 945 (sin phi) (expt (- (expt (sin phi) 2) 1) 2)))
|
(5 (* 945 (expt (cos phi) 5)))
|
))
|
(6
|
(ecase (abs degree)
|
(0 (+ (- (/ (* 231 (expt (cos phi) 6)) 16)) (/ (* 189 (expt (cos phi) 4)) 8) (- (/ (* 21 (expt (cos phi) 2)) 2)) 1))
|
(1 (/ (* 21 (sin (* 2 phi)) (+ (* 33 (expt (sin phi) 4)) (- (* 30 (expt (sin phi) 2))) 5)) 16))
|
(2 (/ (* 105 (expt (cos phi) 2) (+ (* 33 (expt (cos phi) 4)) (- (* 48 (expt (cos phi) 2))) 16)) 8))
|
(3 (- (/ (* 315 (expt (cos phi) 3) (sin phi)) (- (* 11 (expt (cos phi) 2)) 8)) 2))
|
(4 (- (/ (* 945 (expt (cos phi) 4) (- (* 11 (expt (cos phi) 2)) 10)) 2)))
|
(5 (* 10395 (expt (cos phi) 5) (sin phi)))
|
(6 (* 10395 (expt (cos phi) 6)))
|
))
|
(7
|
(ecase (abs degree)
|
(0 (/ (* (sin phi) (+ (* 429 (expt (sin phi) 6)) (- (* 693 (expt (sin phi) 4))) (* 315 (expt (sin phi) 2)) (- 35))) 16))
|
(1 (- (/ (* (* 7 (cos phi)) (+ (* 429 (expt (cos phi) 6)) (- (* 792 (expt (cos phi) 4))) (* 432 (expt (cos phi) 2)) (- 64))) 16)))
|
(2 (- (/ (* 63 (sin phi) (- (expt (sin phi) 2) 1) (+ (* 143 (expt (sin phi) 4)) (- (* 110 (expt (sin phi) 2))) 15)) 8)))
|
(3 (/ (* (* 315 (expt (cos phi) 3)) (+ (* 143 (expt (cos phi) 4)) (- (* 220 (expt (cos phi) 2))) 80)) 8))
|
(4 (/ (* 3465 (sin phi) (- (* 13 (expt (sin phi) 2)) 3) (expt (- (expt (sin phi) 2) 1) 2)) 2))
|
(5 (- (/ (* 10395 (expt (cos phi) 5) (- (* 13 (expt (cos phi) 2)) 12)) 2)))
|
(6 (* -135135 (sin phi) (expt (- (expt (sin phi) 2) 1) 3)))
|
(7 (* 135135 (expt (cos phi) 7)))
|
))
|
)
|
))
|
|
|
|
; ####### High-level API ##########
|
|
|
(defun sox-hoaencode-gain-single-component (order degree azimuth_deg elevation_deg)
|
"Returns the gain value (linear, -1 to 1) for a single ACN-channel"
|
(let
|
(
|
; It is assumed that azimuth_deg follows the implementation details of SpatDIF,
|
; where azimuth_deg runs counterclockwise.
|
; However, the formulas inside assume that azimuth_deg runs clockwise, i.e.
|
; the sign of azimuth_deg must be inverted.
|
(azimuth_deg_inverted (* -1 azimuth_deg))
|
)
|
(*
|
(sox-hoaencode-sn3d-factor order degree)
|
(sox-hoaencode-azimuth-factor degree azimuth_deg_inverted)
|
(sox-hoaencode-elevation-factor order degree elevation_deg)))
|
)
|
|
|
(defun sox-hoaencode-gains-by-order (order azimuth_deg elevation_deg)
|
"Returns the gain values for all components at a specific order"
|
(loop for degree from (* -1 order) to order collect
|
(sox-hoaencode-gain-single-component order degree azimuth_deg elevation_deg)))
|
|
|
(defun sox-hoaencode-gains-up-to-order (order azimuth_deg elevation_deg)
|
"Returns the gain values for all components up to a specific order"
|
(sox-hoaencode-double-to-float
|
(flatten
|
(loop for ord from 0 to order collect
|
(sox-hoaencode-gains-by-order ord azimuth_deg elevation_deg)))))
|
|
|
; ####### SoX-HOAENCODE class ##########
|
|
(defclass! sox-hoaencode (sox-input)
|
(
|
(gains :accessor gains :initarg :gains :initform nil :documentation *sox-gain-doc*)
|
(azimuth :accessor azimuth :initarg :azimuth :initform 0 :documentation "azimuth angle in degrees")
|
(elevation :accessor elevation :initarg :elevation :initform 0 :documentation "elevation angle in degrees")
|
(order :accessor order :initarg :order :initform 3 :documentation *sox-hoaencode-order-doc*)
|
)
|
(:icon 100)
|
(:documentation "Sox-hoaencode encodes <sound> into a <order>-th ambisonic (HOA) signal at <positions>.
|
|
The signal follows the ambiX convention, i.e. it uses SN3D normalization and ACN channel ordering. The resulting file has (<order>+1)^2 channels (order 0: 1 channel, order 1: 4 channels, order 2: 9 channels, order 3: 16 channels, ...).")
|
)
|
|
(defmethod initialize-instance :after ((self sox-hoaencode) &rest l)
|
(declare (ignore l))
|
(when (sound self)
|
(sox-init-sound self 'atom)
|
)
|
)
|
