::tomato::mathvec3dTop, Main, Index

method constructor {args} {

    # Initializes a new Vector3d Class.
    #
    # args - Options described below.
    #
    # Class      - A Class [Vector3d].
    # List       - A Tcl list including 3 components values.
    # values     - 3 components values.
    # no values  - default to `Vector3d(0.0, 0.0, 1.0)`.
    #
    if {[llength $args] == 1} {
        # args Class Vector3d
        if {[tomato::helper::TypeOf $args Isa "Vector3d"]} {

            set _x [$args X]
            set _y [$args Y]
            set _z [$args Z]

        # args list > ex : Vector3d new {1 2 3}
        } elseif {[llength {*}$args] == 3} {
            lassign {*}$args x y z

            set _x $x
            set _y $y
            set _z $z

        } else {
            error "Must be a list of 3 values or 'Vector3d' class"
        }

    # args values > ex : Vector3d new 1 2 3
    } elseif {[llength $args] == 3} {
        lassign $args x y z

        set _x $x
        set _y $y
        set _z $z
    } elseif {[llength $args] == 0} {
        # default values
        set _x 0.0
        set _y 0.0
        set _z 1.0
    } else {
        #ruff
        # An error exception is raised if `args` is not the one desired.
        error "The argument does not match the requested values, please refer to the documentation..."
    }
}

method != {other {tolerance {$::tomato::helper::TolEquals}}} {

    # Gets value that indicates whether any pair of elements in two specified vectors is not equal.
    #
    # other - The second vector [Vector3d] to compare.
    # tolerance - A tolerance (epsilon) to adjust for floating point error.
    #
    # Returns `True` if the vectors are different. Otherwise `False`.
    if {[llength [info level 0]] < 4} {
        set tolerance $::tomato::helper::TolEquals
    }

    return [expr {![tomato::mathvec3d::Equals [self] $other $tolerance]}]
}

method * {type} {

    # Multiplies a vector by a scalar if $type is a scale
    # or Compute the Dot product if $type is an object.
    #
    # type - Options described below.
    #
    # scalar - A scalar component.
    # object - A object component.
    #
    # Returns A new scaled vector [Vector3d] if scalar or A scalar result if object.
    if {[tomato::helper::IsaObject $type]} {
        return [my DotProduct $other]
    } else {

        set vx [expr {$_x * $type}]
        set vy [expr {$_y * $type}]
        set vz [expr {$_z * $type}]

        return [tomato::mathvec3d::Vector3d new $vx $vy $vz]

    }
}

method + {other} {

    # Adds two vectors
    #
    # other - The other vector [Vector3d] Object.
    #
    # Returns A new summed vector [Vector3d].
    set vx [expr {$_x + [$other X]}]
    set vy [expr {$_y + [$other Y]}]
    set vz [expr {$_z + [$other Z]}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

method - {other} {

    # Subtracts two vectors
    #
    # other - The other vector [Vector3d] Object.
    #
    # Returns A new difference vector [Vector3d].
    set vx [expr {$_x - [$other X]}]
    set vy [expr {$_y - [$other Y]}]
    set vz [expr {$_z - [$other Z]}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

method / {scale} {

    # Divides a vector by a scalar.
    #
    # scale - A scalar
    #
    # Returns A new scaled vector [Vector3d].
    if {$scale == 0} {
        error "Divide [tomato::helper::TypeClass [self]] by zero..."
    }

    set vx [expr {$_x / $scale}]
    set vy [expr {$_y / $scale}]
    set vz [expr {$_z / $scale}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

method == {other {tolerance {$::tomato::helper::TolEquals}}} {

    # Gets value that indicates whether each pair of elements in two specified vectors is equal.
    #
    # other     - The second vector [Vector3d] to compare.
    # tolerance - A tolerance (epsilon) to adjust for floating point error.
    #
    # Returns `True` if the vectors are the same. Otherwise `False`.
    if {[llength [info level 0]] < 4} {
        set tolerance $::tomato::helper::TolEquals
    }

    return [expr {[tomato::mathvec3d::Equals [self] $other $tolerance]}]
}

method AngleTo {v} {

    # Compute the angle between this vector and another using the arccosine of the dot product.
    #
    # v - The other vector [Vector3d]
    #
    # Returns The angle in radian between the vectors, with a range between 0° and 180°
    set uv1 [my Normalized]
    set uv2 [$v Normalized]

    # Formatting value to avoid error : 'argument not in valid range'
    # ex with this value : 1.0000000000000002
    set t     [regexp -inline {[0-9]+$} $::tomato::helper::TolGeom]
    set dp    [format "%.${t}f" [$uv1 DotProduct $uv2]]
    set angle [expr {acos($dp)}]

    return $angle
}

method Cget {axis} {

    # Gets component value.
    #
    # axis - Options described below.
    #
    # -X - The x component.
    # -Y - The y component.
    # -Z - The z component.
    switch -exact -- $axis {
        "-X" {return $_x}
        "-Y" {return $_y}
        "-Z" {return $_z}
        default {error "Unknown key '$key' : $axis"}
    }
}

method Configure {args} {

    # Configure component value.
    #
    # args - Options described below.
    #
    # -X - The x component.
    # -Y - The y component.
    # -Z - The z component.
    foreach {key value} $args {

        if {$value eq ""} {
            error "No value specified for key '$key'"
        }

        switch -exact -- $key {
            "-X"    {set _x $value}
            "-Y"    {set _y $value}
            "-Z"    {set _z $value}
            default {error "Unknown key '$key' specified"}
        }
    }
}

method CrossProduct {other} {

    # Compute the cross product of this vector and another vector
    #
    # other - The other vector [Vector3d] Object.
    #
    # Returns A new vector with the cross product result.
    return [tomato::mathvec3d::Cross [self] $other]
}

method CrossProductMatrix {} {

     # A matrix containing the cross product of this vector
     #
     # Returns a matrix [mathmatrix::Matrix]
     set mat [tomato::mathmatrix::Matrix new 3 3]

     $mat SetCell 0 0 0.0
     $mat SetCell 1 0 $_z
     $mat SetCell 2 0 [expr {Inv($_y)}]
     $mat SetCell 0 1 [expr {Inv($_z)}]
     $mat SetCell 1 1 0.0
     $mat SetCell 2 1 $_x
     $mat SetCell 0 2 $_y
     $mat SetCell 1 2 [expr {Inv($_x)}]
     $mat SetCell 2 2 0.0

    return $mat
}

method DotProduct {other} {

    # Compute the dot product of two vectors.
    #
    # other - The other vector [Vector3d] Object.
    #
    # Returns the dot product.
    return [tomato::mathvec3d::Dot [self] $other]
}

method Get {} {

    # Gets values from the Vector3D Class under Tcl list form.
    return [list $_x $_y $_z]
}

method GetType {} {

    # Gets the name of class.
    return [tomato::helper::TypeClass [self]]
}

method GetUnitTensorProduct {} {

    # A matrix with the unit tensor product<br>
    # `[ux^2,  ux*uy, ux*uz]`<br>
    # `[ux*uy, uy^2,  uy*uz]`<br>
    # `[ux*uz, uy*uz, uz^2]`
    #
    # Returns a matrix [mathmatrix::Matrix]

    set xy [expr {$_x * $_y}]
    set xz [expr {$_x * $_z}]
    set yz [expr {$_y * $_z}]

    set mat [tomato::mathmatrix::Matrix new 3 3]

    $mat SetCell 0 0 [expr {$_x * $_x}]
    $mat SetCell 1 0 $xy
    $mat SetCell 2 0 $xz
    $mat SetCell 0 1 $xy
    $mat SetCell 1 1 [expr {$_y * $_y}]
    $mat SetCell 2 1 $yz
    $mat SetCell 0 2 $xz
    $mat SetCell 1 2 $yz
    $mat SetCell 2 2 [expr {$_z * $_z}]

    return $mat
}

method IsNormalized {{tolerance {$::tomato::helper::TolGeom}}} {

    # Check if vector is normalized.
    #
    # tolerance - The allowed deviation
    #
    # Returns `True`, if the Vector object is normalized. Otherwise `False`.
    if {[llength [info level 0]] < 3} {
        set tolerance $::tomato::helper::TolGeom
    }

    set norm [my Length]

    if {abs($norm - 1.0) < $tolerance} {
        return true
    }

    return false
}

method IsParallelTo {other {tolerance {$::tomato::helper::TolGeom}}} {

    # Computes whether or not this vector is parallel to another vector using the Cross product method and comparing it
    # to within a specified tolerance.
    #
    # other - The other vector [Vector3d] Object.
    # tolerance - A tolerance value for the Cross product method.
    #
    # Returns `True` if the vector dot product is within the given tolerance of unity, false if it is not.
    if {[llength [info level 0]] < 4} {
        set tolerance $::tomato::helper::TolGeom
    }

    set vaN    [my Normalized]
    set otherN [$other Normalized]

    set cross [$vaN CrossProduct $otherN]
    set det   [$cross LengthSquared]

    return [expr {abs($det) <= $tolerance}]
}

method IsPerpendicularTo {other {tolerance {$::tomato::helper::TolGeom}}} {

    # Computes whether or not this vector is perpendicular to another vector using the dot product method and
    # comparing it to within a specified tolerance
    #
    # other - The other vector [Vector3d] Object.
    # tolerance - A tolerance value for the dot product method.
    #
    # Returns `True` if the vector dot product is within the given tolerance of zero, false if not.
    if {[llength [info level 0]] < 4} {
        set tolerance $::tomato::helper::TolGeom
    }

    set vaN    [my Normalized]
    set otherN [$other Normalized]

    set dp [expr {abs([$vaN DotProduct $otherN])}]
    return [expr {$dp < $tolerance}]
}

method Length {} {

    # Gets the Euclidean Norm.
    return [expr {sqrt(($_x**2) + ($_y**2) + ($_z**2))}]
}

method LengthSquared {} {

    # Gets the length of the vector squared
    return [expr {($_x**2) + ($_y**2) + ($_z**2)}]
}

method Negate {} {

    # Inverses the direction of the vector
    #
    # Returns a new vector [Vector3d] pointing in the opposite direction
    return [tomato::mathvec3d::Vector3d new [expr {Inv($_x)}] [expr {Inv($_y)}] [expr {Inv($_z)}]]
}

method Normalize {} {

    # Transform self Vector to Normalize Vector.
    #
    # Returns nothing.
    #
    # See also: Normalized IsNormalized
    set norm [my Length]

    if {$norm == 0.0} {
        error "The Euclidean norm of x, y, z is equal to 0..."
    }

    set scale [expr {1.0 / $norm}]

    set _x [expr {$_x * $scale}]
    set _y [expr {$_y * $scale}]
    set _z [expr {$_z * $scale}]

    return {}
}

method Normalized {} {

    # Compute and return a copy unit vector from this vector
    #
    # Returns a copy normalized unit vector [Vector3d] if necessary.
    set vec [self]

    if {[$vec IsNormalized]} {
        return $vec
    }

    set v [oo::copy $vec]
    $v Normalize
    return $v
}

method Orthogonal {} {

    # Gets a unit vector orthogonal to this
    #
    # Returns a new vector Normalized [Vector3d].
    if {(Inv($_x) - $_y) > 0.1} {
        set v [tomato::mathvec3d::Vector3d new $_z $_z [expr {Inv($_x) - $_y}]]
        $v Normalize
        return $v
    }

    set v [tomato::mathvec3d::Vector3d new [expr {Inv($_y) - $_z}] $_x $_x]
    $v Normalize
    return $v
}

method ProjectOn {obj} {

    # Projects the vector onto a plane if $obj is a plane
    # The Dot product of the current vector and a unit vector if $obj is a vector.
    #
    # obj - Options described below.
    #
    # Vector3d - [Vector3d]
    # Plane    - [mathplane::Plane]
    #
    # Returns a new vector [Vector3d] if $obj is a vector or a new Ray if $obj is a [mathplane::Plane].
    switch -glob [$obj GetType] {
        *Vector3d {
            set pd [my DotProduct [$obj Normalized]]
            return [$obj * $pd]
        }
        *Plane {
            return [$obj Project [self]]
        }
        default {
            error "Obj must be Vector3d or Plane..."
        }
    }
}

method Rotate {aboutVector angle} {

    # Gets a vector that is this vector rotated the signed angle around the about vector.
    #
    # aboutVector - A vector [Vector3d] to rotate about
    # angle - An angle in degree
    #
    # Returns a rotated vector [Vector3d].
    set cs [tomato::mathcsys::RotationAngleVector $angle [$aboutVector Normalized]]
    return [$cs Transform [self]]
}

method ScaleBy {scaleFactor} {

    # Multiplies the current vector by a scalar
    #
    # scaleFactor - a scalar
    #
    # Returns a new scaled vector [Vector3d]
    return [my * $scaleFactor]
}

method SignedAngleTo {v about} {

    # Gets signed angle.
    #
    # v     - The vector [Vector3d] to calculate the signed angle to
    # about - The vector [Vector3d] around which to rotate to get the correct sign
    #
    # Returns A signed Angle (In radian).
    if {[my IsParallelTo $about]} {
        error "Self parallel to aboutVector"
    }

    if {[$v IsParallelTo $about]} {
        error "FromVector parallel to aboutVector"
    }

    set rp  [tomato::mathplane::Plane new [tomato::mathpt3d::Point3d new 0 0 0] $about]
    set pfv [[my ProjectOn $rp] Direction]
    set ptv [[$v ProjectOn $rp] Direction]
    set dp  [$pfv DotProduct $ptv]

    if {abs($dp - 1.0) < 1e-15} {return 0}
    if {abs($dp + 1.0) < 1e-15} {return [expr {Pi()}]}

    set angle       [expr {acos($dp)}]
    set cpv         [$pfv CrossProduct $ptv]
    $cpv Normalize
    set sign        [$cpv DotProduct [$rp Normal]]
    set signedAngle [expr {$sign * $angle}]

    return $signedAngle
}

method ToPoint3D {} {

    # A point equivalent to the vector
    #
    # Returns a new Point3d [mathpt3d::Point3d]
    return [tomato::mathpt3d::Point3d new $_x $_y $_z]
}

method ToString {} {

    # Returns a string representation of this object.
    return [format {%s, %s, %s} $_x $_y $_z]
}

method TransformBy {obj} {

    # Transforms the vector by a coordinate system
    #
    # obj - Options described below.
    #
    # Matrix           - [mathmatrix::Matrix]
    # coordinatesystem - [mathcsys::Csys]
    #
    # Returns a new transformed vector [Vector3d]
    switch -glob [$obj GetType] {
        *Csys {
            return [$obj Transform [self]]
        }
        *Matrix {
            lassign [$obj Multiply [self]] x y z
            return [tomato::mathvec3d::Vector3d new $x $y $z]
        }
        default {
            error "Obj must be Matrix or Csys..."
        }
    }
}

method X {} {

    # Returns The x component.
    return $_x
}

method Y {} {

    # Returns The y component.
    return $_y
}

method Z {} {

    # Returns The z component.
    return $_z
}

proc ::tomato::mathvec3d::Clamp {vec min max} {

    # Clamp a vector to the given minimum and maximum vectors.
    #
    # vec - Input vector   [Vector3d]
    # min - Minimum vector [Vector3d]
    # max - Maximum vector [Vector3d]
    #
    # Returns a new clamped vector [Vector3d].
    set vx [expr {[$vec X] < [$min X] ? [$min X] : [$vec X] > [$max X] ? [$max X] : [$vec X]}]
    set vy [expr {[$vec Y] < [$min Y] ? [$min Y] : [$vec Y] > [$max Y] ? [$max Y] : [$vec Y]}]
    set vz [expr {[$vec Z] < [$min Z] ? [$min Z] : [$vec Z] > [$max Z] ? [$max Z] : [$vec Z]}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

proc ::tomato::mathvec3d::ComponentMax {v1 v2} {

    # A vector created from the largest of the corresponding components of the given vectors.
    #
    # v1 - [Vector3d]
    # v2 - [Vector3d]
    #
    # Returns a new vector [Vector3d] component-wise maximum.
    set vx [expr {[$v1 X] > [$v2 X] ? [$v1 X] : [$v2 X]}]
    set vy [expr {[$v1 Y] > [$v2 Y] ? [$v1 Y] : [$v2 Y]}]
    set vz [expr {[$v1 Z] > [$v2 Z] ? [$v1 Z] : [$v2 Z]}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

proc ::tomato::mathvec3d::ComponentMin {v1 v2} {

    # A vector created from the smallest of the corresponding components of the given vectors.
    #
    # v1 - [Vector3d]
    # v2 - [Vector3d]
    #
    # Returns a new vector [Vector3d] component-wise minimum.
    set vx [expr {[$v1 X] < [$v2 X] ? [$v1 X] : [$v2 X]}]
    set vy [expr {[$v1 Y] < [$v2 Y] ? [$v1 Y] : [$v2 Y]}]
    set vz [expr {[$v1 Z] < [$v2 Z] ? [$v1 Z] : [$v2 Z]}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

proc ::tomato::mathvec3d::Cross {v1 v2} {

    # Compute the cross product of 2 vectors
    #
    # v1 - [Vector3d]
    # v2 - [Vector3d]
    #
    # See : method CrossProduct
    set vx [expr {([$v1 Y] * [$v2 Z]) - ([$v1 Z] * [$v2 Y])}]
    set vy [expr {([$v1 Z] * [$v2 X]) - ([$v1 X] * [$v2 Z])}]
    set vz [expr {([$v1 X] * [$v2 Y]) - ([$v1 Y] * [$v2 X])}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

proc ::tomato::mathvec3d::Dot {v1 v2} {

    # Compute the dot product of 2 vectors
    #
    # v1 - [Vector3d]
    # v2 - [Vector3d]
    #
    # See : method DotProduct
    return [expr {([$v1 X] * [$v2 X]) + ([$v1 Y] * [$v2 Y]) + ([$v1 Z] * [$v2 Z])}]
}

proc ::tomato::mathvec3d::Equals {vector other tolerance} {

    # Indicate if this vector is equivalent to a given unit vector
    #
    # vector - First input vector [Vector3d]
    # other - Second input vector [Vector3d]
    # tolerance - A tolerance (epsilon) to adjust for floating point error
    #
    # Returns `True` if the vectors are equal, otherwise false.
    #
    # See : methods == !=
    if {$tolerance < 0} {
        #ruff
        # An error exception is raised if tolerance (epsilon) < 0.
        error "epsilon < 0"
    }

    return [expr {
                  (abs([$other X] - [$vector X]) < $tolerance) &&
                  (abs([$other Y] - [$vector Y]) < $tolerance) &&
                  (abs([$other Z] - [$vector Z]) < $tolerance)
                }]
}

proc ::tomato::mathvec3d::Lerp {v1 v2 blend} {

    # Lerp a new Vector that is the linear blend of the 2 given Vectors.
    #
    # v1 - [Vector3d]
    # v2 - [Vector3d]
    # blend - The blend factor. v1 when `blend=0`, v2 when `blend=1`.
    #
    # Returns v1 when `blend=0`, v2 when `blend=1`, and a linear combination otherwise.
    set vx [expr {$blend * ([$v2 X] - [$v1 X]) + [$v1 X]}]
    set vy [expr {$blend * ([$v2 Y] - [$v1 Y]) + [$v1 Y]}]
    set vz [expr {$blend * ([$v2 Z] - [$v1 Z]) + [$v1 Z]}]

    return [tomato::mathvec3d::Vector3d new $vx $vy $vz]
}

proc ::tomato::mathvec3d::MagnitudeMax {left right} {

    # A vector with the maximum magnitude.
    #
    # left  - [Vector3d]
    # right - [Vector3d]
    #
    # Returns Vector [Vector3d] magnitude-wise maximum.
    return [expr {[$left Length] >= [$right Length] ? $left : $right}]
}

proc ::tomato::mathvec3d::MagnitudeMin {left right} {

    # A vector with the minimum magnitude
    #
    # left  - [Vector3d]
    # right - [Vector3d]
    #
    # Returns Vector [Vector3d] magnitude-wise minimum.
    return [expr {[$left Length] < [$right Length] ? $left : $right}]
}

proc ::tomato::mathvec3d::UnitX {} {

    # A unit length Vector X-axis
    #
    # Returns a unit length vector [Vector3d] that points towards the X-axis
    return [tomato::mathvec3d::Vector3d new 1.0 0.0 0.0]
}

proc ::tomato::mathvec3d::UnitY {} {

    # A unit length Vector Y-axis
    #
    # Returns a unit length vector [Vector3d] that points towards the Y-axis
    return [tomato::mathvec3d::Vector3d new 0.0 1.0 0.0]
}

proc ::tomato::mathvec3d::UnitZ {} {

    # A unit length Vector Z-axis
    #
    # Returns a unit length vector [Vector3d] that points towards the Z-axis
    return [tomato::mathvec3d::Vector3d new 0.0 0.0 1.0]
}