;Authors: 
; A. Nguyen, 2025
; M. Schumacher, 2025

; Design limitations:
; 1) Sounds must have identical sample rate; otherwise, SoX fails silently, literally.

; Questions:
; 1) Is there a built-in (flatten lst)-function? Yes, om:flat
; 2) Implement up to which order? <=> CLI issues to be expected (e.g., maximum command character length)? max character length for CLI should be changeable 

(in-package :om)

;;; SOX-HOAENCODE ========================

; Util
(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 ###

(defun sox-hoaencode-sn3d-factor (order degree)
"This is a placeholder for documentation"
    (ecase order
        (0 1)
        (1 1)
        (2 
            (ecase (abs degree)
                (2 (/ (sqrt 3) 6))
                (1 (/ (sqrt 3) 3))
                (0 1)
            ))
        (3 
            (ecase (abs degree)
                (3 (/ (sqrt 10) 60))
                (2 (/ (sqrt 15) 30))
                (1 (/ (sqrt 6) 6))
                (0 1)
            )
        )
    )
)

(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 (expt (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)))
                ))
        )
    ))

; #### Utility functions ####

#|
(defun sox-hoaencode-auto-convert-positions (positions)
"Ensures that positions are given as '((azimuth elevation) ...) (in degrees), i.e.
1) if list of list of three values, input is assumed to be '(x y z) coordinates and will be transformed to '(azimuth elevation) coordinates (in the navigational spherical coordinate system).
2) if list of list of two values, input is assumed to be '(azimuth elevation) coordinates and won't be transformed any further.
3) if 3dc, input is transformed to '(azimuth elevation) coordinates.
"
    (cond 
        ((subtypep (type-of positions) '3dc)  
            (progn ; convert xyz->aed, keep azimuth and elevation only.
                (mat-trans 
                    (butlast 
                        (mat-trans 
                            (mapcar 
                                (lambda (xyz) (multiple-value-list (om:xyz->aed (first xyz) (second xyz) (third xyz)))) 
                                (mat-trans (list (x-points positions) (y-points positions) (z-points positions)))
                            ))))))
        ((subtypep (type-of positions) 'list) 
            (cond
                ((= 2 (length (first positions)))
                    positions)
                ((= 3 (length (first positions))) 
                    (mat-trans 
                        (butlast 
                            (mat-trans 
                                (mapcar 
                                    (lambda (xyz) (multiple-value-list (om:xyz->aed (first xyz) (second xyz) (third xyz)))) 
                                    positions
                                )))))
                (t (error "Positions must consist of lists of length 2 (ae) or 3 (xyz)."))
            ))
        (t (error "Positions must be of type 3dc or list."))))
|#


; ####### 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)))
    )

; (sox-hoaencode-gain-single-component 1 1 45 0)
; what is the difference between "order" and "degree"?


(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)))))


(defclass! sox-hoaencode (sox-input)
    (
     (gain :accessor gain :initarg :gain :initform 0 :documentation "gain value in dB (decibel)")
     (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)
    )
)