Path.ele

constraint PathFunc(u:Num):Vector3
struct Bounds(lower:Num, upper:Num)

#[[ A Path is defined by a parametric equation of a path,
#   and a domain over which the function is valid.
#]]
struct Path(at:PathFunc, domain:Bounds)
{
    constraint ScalarTransform(x:Num):Num
    constraint Vector3Unary(v:Vector3):Vector3
    constraint Vector3Binary(v1:Vector3, v2:Vector3):Vector3

    #[[ Change the path domain from the current domain "newDomain".
    #
    #   This function returns a new path where the "newDomain" maps
    #   onto the original domain.
    #
    #   This returned path, "newPath" has the properties:
    #       newPath.domain = newDomain
    #       newPath.at(newDomain.lower) = this.at(this.domain.lower)
    #       newPath.at(newDomain.upper) = this.at(this.domain.upper)
    #]]
    changeDomain(this:Path, newDomain:Bounds):Path
    {
        uTransform(u:Num):Num
        {
            return = Num.lerp(u.sub(newDomain.lower).div(newDomain.upper.sub(newDomain.lower)), this.domain.lower, this.domain.upper)
        }
        transformedPathFunc(u:Num):Vector3 = this.at(uTransform(u))
        return = Path(transformedPathFunc, newDomain)
    }

    #[[ Returns a path which pingPongs along the original path
    #   in the original domain.
    #
    #   Eg, if the original domain is (0, 1) then the returned
    #   path also has a domain (0, 1). Over this domain, the returned
    #   path travels to the end of the original path and back again.
    #
    #   newPath.domain = oldPath.domain
    #   newPath.at(0) = oldPath.at(0)
    #   newPath.at(0.5) = oldPath.at(1)
    #   newPath.at(1) = oldPath.at(0)
    #
    #   This means that the path length is double the original path length.
    #]]
    pingPong(this:Path):Path
    {
        unitIntervalTransform(u:Num):Num = if(u.gt(0.5), 1.sub(u).mul(2), u.mul(2))
        return = this.applyUnitIntervalTransformToDomain(unitIntervalTransform)
    }

    #[[ Returns the same path repeated "repetitions" times over
    #   the same domain.
    #
    #   This changes the path length.
    #]]
    repeat(this:Path, repetitions:Num):Path
    {
        unitIntervalTransform(u:Num):Num = u.mul(repetitions).rem(1)
        return = this.applyUnitIntervalTransformToDomain(unitIntervalTransform)
    }

    reverse(this:Path):Path
    {
        uTransform(u:Num):Num
        {
            w = u.sub(this.domain.lower)
            return = this.domain.upper.sub(w)
        }
        transformedPathFunc(u:Num):Vector3 = this.at(uTransform(u))
        return = Path(transformedPathFunc, this.domain)
    }

    oscillate(this:Path):Path
    {
        unitIntervalTransform(u:Num):Num = Num.sub(0.5, Num.cos(u.mul(Num.tau)).div(2))
        return = this.applyUnitIntervalTransformToDomain(unitIntervalTransform)
    }

    #[[ Map 0 to 1 to the same range, but more smoothly ]]
    easing(this:Path):Path
    {
        smoothstep(t:Num):Num = 3.mul(t).mul(t).sub(2.mul(t).mul(t).mul(t))
        return = this.applyUnitIntervalTransformToDomain(smoothstep)
    }

    #[[ Quantise the positions on the path with nSteps ]]
    quantise(this:Path, nSteps:Num):Path
    {
        uiTransform(u:Num):Num
        {
            return = u.mul(nSteps).floor.div(nSteps.sub(1))
        }
        return = this.applyUnitIntervalTransformToDomain(uiTransform)
    }

    #[[ Concatenate multiple paths
    #
    #   Supply a list of paths and their corresponding lengths.
    #
    #   The input needs to be a list of anonymous blocks, each
    #   with a 'path' and a 'length' field (see example below).
    #
    #   Note that the absolute values of the lengths do not need to
    #   be accurate, only their relative values are used. All pathLengths
    #   must be positive numbers.
    #
    #   Usage:
    #       path1 = Path(...)
    #       path2 = Path(...)
    #       length1 = (...)
    #       length2 = (...)
    #       result = concatAll(
    #           list(
    #               {path=path1, length=length1},
    #               {path=path2, length=length2}
    #           )
    #       )
    #
    #]]
    concatAll(pathsAndLengths:List):Path
    {
        firstPathAndLength = pathsAndLengths.at(0)
        otherPathsAndLengths = pathsAndLengths.skip(1)

        accumulator(current, next)
        {
            lengthRatio = next.length.div(current.length)
            newPath = current.path.concatByLengthRatio(next.path, lengthRatio)

            newLength = current.length.add(next.length)
            return = {path=newPath, length=newLength}
        }

        return = otherPathsAndLengths.fold(firstPathAndLength, accumulator).path
    }

    #[[ Concatenate two paths by specifying the length ratio
    #
    #   The "lengthRatio" needs to be (path2Length / path1Length)
    #
    #   The new path has a domain (0, 1), and goes along path1 and
    #   then path2. The lengthRatio is used to determine where in this
    #   domain path1 should end and path2 should begin.
    #]]
    concatByLengthRatio(path1:Path, path2:Path, lengthRatio:Num):Path
    {
        #   The domain boundary is calculated by
        #   boundary = length1 / (length1 + length2)
    
        boundary = 1.div(1.add(lengthRatio))
        return = concatByDomainBoundary(path1, path2, boundary)
    }

    #[[ Concatenate two paths by specifying the new domain boundary
    #
    #   The output path has a domain (0, 1)
    #
    #   The "boundary" parameter defines at which point in this domain
    #   "path1" should end and "path1" should begin.
    #
    #   The domain (0, boundary) maps to the domain of path1, and
    #   the domain (boundary, 1) maps to the domain of path2
    #]]
    concatByDomainBoundary(path1:Path, path2:Path, boundary:Num):Path
    {
        pathA = path1.changeDomain(Bounds(0, boundary))
        pathB = path2.changeDomain(Bounds(boundary, 1))

        newPathFunction(u:Num):Vector3 = if(u.leq(boundary), pathA.at(u), pathB.at(u))

        return = Path(newPathFunction, Bounds(0, 1))
    }

    #[[ Combine the two paths by adding the positions at each point
    #
    #   The two paths must have the same domain for this operation to be valid.
    #   If they are not the same, the domain of path1 will be used.
    #]]
    add(path1:Path, path2:Path):Path
    {
        return = Path.applyBinaryVectorOperation(path1, path2, Vector3.add)
    }

    #[[ Apply a Transform to all points on the path ]]
    applyTransform(this:Path, transform:Transform):Path
    {
        return = applyUnaryVectorOperation(this, transform.applyToPosition)
    }

    #[[ Apply an offset to the path ]]
    applyOffset(this:Path, offset:Vector3):Path
    {
        adder = _(v:Vector3):Vector3 = v.add(offset)
        return = applyUnaryVectorOperation(this, adder)
    }

    #[[ Apply an operation to all points on the path ]]
    applyUnaryVectorOperation(this:Path, operation:Vector3Unary):Path
    {
        newPathFunction(u:Num):Vector3 = operation(this.at(u))
        return = Path(newPathFunction, this.domain)
    }

    #[[ Combine the two paths by applying the binary operation at each point
    #
    #   The two paths must have the same domain for this operation to be valid.
    #   If they are not the same, the domain of path1 will be used.
    #]]
    applyBinaryVectorOperation(path1:Path, path2:Path, operation:Vector3Binary):Path
    {
        newPathFunction(u:Num):Vector3
        {
            path1Pos = path1.at(u)
            path2Pos = path2.at(u)
            return = operation(path1Pos, path2Pos)
        }
        return = Path(newPathFunction, path1.domain)
    }

    #[[ Apply the unitIntervalTransform to the path inputs over the domain
    #
    #   The unitIntervalTransform must map a point in the range (0, 1) to another point in this range.
    #   The returned Path has the same domain at the original Path, but with the transform applied
    #   to all inputs.
    #]]
    applyUnitIntervalTransformToDomain(this:Path, unitIntervalTransform:ScalarTransform):Path
    {

        domainTransform(u:Num):Num
        {
            domainLength = this.domain.upper.sub(this.domain.lower)
            w = u.sub(this.domain.lower).div(domainLength)
            wNew = unitIntervalTransform(w)
            return = wNew.mul(domainLength).add(this.domain.lower)
        }
        transformedPathFunc(u:Num):Vector3 = this.at(domainTransform(u))
        return = Path(transformedPathFunc, this.domain)
    }
}