adding documentation for the sequential scales and initial interpolators

Author: heckj

Sources/SwiftVizScale/ArrayInterpolator.swift

@@ -4,7 +4,18 @@
 
 import CoreGraphics
 
-public struct ArrayInterpolator: Interpolator {
+///// A type that provides an interpolated result types between two corresponding instances.
+// public protocol Interpolator {
+//    /// The type that the interpolator accepts as instances, and returns as an interpolated result.
+//    associatedtype OutputType
+//    /// Provide an instance that is the interpolated value between two others.
+//    /// - Parameter t: A unit value between `0` and `1` that represents the distance between the two values.
+//    /// - Returns: An instance of a type that is the interpolated result based on the value you provide.
+//    func interpolate(_ t: Double) -> OutputType
+// }
+
+/// An interpolator that maps a unit value into a color based on the position between the colors.
+public struct ArrayInterpolator {
     // Color pallets for interpolation and presentation:
     // https://github.com/d3/d3-scale-chromatic/blob/main/README.md
     var colors: [CGColor]
@@ -33,23 +44,41 @@ public struct ArrayInterpolator: Interpolator {
         return (lowerIndex, tValueBetweenSteps)
     }
 
+    /// Returns the color mapped from the unit value you provide.
+    /// - Parameter t: A unit value between `0` and  `1`.
     public func interpolate(_ t: Double) -> CGColor {
         let (colorIndex, tBetweenIndicies) = Self.interpolateIntoSteps(t, colors.count - 1)
         return LCH.interpolate(colors[colorIndex], colors[colorIndex + 1], t: tBetweenIndicies)
     }
 
+    /// Creates a new color interpolator that maps between the two colors you provide.
+    /// - Parameters:
+    ///   - from: The color at the beginning.
+    ///   - to: The color at the end.
     public init(_ from: CGColor, _ to: CGColor) {
         colors = [from, to]
     }
 
+    /// Creates a new color interpolator that maps between the colors you provide.
+    /// - Parameters:
+    ///   - colors: The sequences of colors to map through.
+    public init(_ colors: [CGColor]) {
+        precondition(colors.count > 2, "ArrayInterpolator requires at least 2 colors.")
+        self.colors = colors
+    }
+
     static let white = CGColor(srgbRed: 1, green: 1, blue: 1, alpha: 1)
     static let black = CGColor(srgbRed: 0, green: 0, blue: 0, alpha: 1)
     static let red = CGColor(srgbRed: 1, green: 0, blue: 0, alpha: 1)
     static let blue = CGColor(srgbRed: 0, green: 0, blue: 1, alpha: 1)
     static let green = CGColor(srgbRed: 0, green: 1, blue: 0, alpha: 1)
 
+    /// An interpolator that maps to various shades between white to black.
     public static let Grays = Self(white, black)
+    /// An interpolator that maps to various shades between white to blue.
     public static let Blues = Self(white, blue)
+    /// An interpolator that maps to various shades between white to green.
     public static let Greens = Self(white, green)
+    /// An interpolator that maps to various shades between white and red.
     public static let Reds = Self(white, red)
 }

Sources/SwiftVizScale/Documentation.docc/ArrayInterpolator.md

@@ -0,0 +1,16 @@
+# ``SwiftVizScale/ArrayInterpolator``
+
+## Topics
+
+### Creating an Interpolator
+
+- ``SwiftVizScale/ArrayInterpolator/Grays``
+- ``SwiftVizScale/ArrayInterpolator/Blues``
+- ``SwiftVizScale/ArrayInterpolator/Greens``
+- ``SwiftVizScale/ArrayInterpolator/Reds``
+- ``SwiftVizScale/ArrayInterpolator/init(_:_:)``
+- ``SwiftVizScale/ArrayInterpolator/init(_:)``
+
+### Mapping values to colors
+
+- ``SwiftVizScale/ArrayInterpolator/interpolate(_:)``

Sources/SwiftVizScale/Documentation.docc/Documentation.md

@@ -29,6 +29,12 @@ Loosely based on the APIs and the visualization constructs created by Mike Bosto
 - ``SwiftVizScale/DiscreteScale``
 - ``SwiftVizScale/DiscreteScaleType``
 
+### Sequential Scales
+
+- ``SwiftVizScale/SequentialScale``
+- ``SwiftVizScale/ArrayInterpolator``
+- ``SwiftVizScale/LCH``
+
 ### Ticks
 
 - ``SwiftVizScale/Tick``
@@ -37,8 +43,6 @@ Loosely based on the APIs and the visualization constructs created by Mike Bosto
 
 - ``SwiftVizScale/Scale``
 - ``SwiftVizScale/ReversibleScale``
-- ``SwiftVizScale/Interpolator``
-- ``SwiftVizScale/LCH``
 - ``SwiftVizScale/NiceValue``
 - ``SwiftVizScale/ConvertibleWithDouble``
 

Sources/SwiftVizScale/Documentation.docc/Interpolator.md

@@ -2,27 +2,121 @@
 //  SequentialScale.swift
 //
 
+import CoreGraphics
 import Foundation
 
-/// A type that maps values from a continuous input _domain_ to an output _range_.
-public struct SequentialScale<InputType: ConvertibleWithDouble, OutputType>: Scale, CustomStringConvertible {
+/// A type that maps values from a continuous input _domain_ to a color.
+public struct SequentialScale<InputType: ConvertibleWithDouble>: CustomStringConvertible {
+    /// The lower bound of the input domain.
+    public let domainLower: InputType
+    /// The upper bound of the input domain.
+    public let domainHigher: InputType
+    /// A Boolean value that indicates if the mapping from domain to range is inverted.
+    public let reversed: Bool
+
+    let interpolator: ArrayInterpolator
+
+    /// Creates a new sequential scale that maps a _domain_ value to a color.
+    /// - Parameters:
+    ///   - lower: The lowest value expected for the scale.
+    ///   - higher: The highest value expected for the scale.
+    ///   - reversed: A Boolean value that indicates the color range is reversed.
+    ///   - interpolator: The interpolator that provides the color range to map.
+    public init(lower: InputType = 0,
+                higher: InputType = 1,
+                reversed: Bool = false,
+                interpolator: ArrayInterpolator)
+    {
+        precondition(lower <= higher, "attempting to set an inverted domain: \(lower) to \(higher)")
+        precondition(lower != higher, "attempting to set an empty domain: \(lower) to \(higher)")
+        domainLower = lower
+        domainHigher = higher
+        self.reversed = reversed
+        self.interpolator = interpolator
+    }
+
+    // MARK: - description
+
+    public var description: String {
+        "sequential[\(domainLower):\(domainHigher)]->\(type(of: interpolator)))"
+    }
+
+    // MARK: - scaling
+
     /// Converts a value comparing it to the input domain, transforming the value, and mapping it between the range values you provide.
     ///
     /// - Parameter inputValue: The value to be scaled.
     /// - Returns: A value within the bounds of the range values you provide, or `nil` if the value was dropped.
-    public func scale(_: InputType) -> OutputType? {
-        nil
+    public func scale(_ x: InputType) -> CGColor {
+        let clampedX: InputType
+        if x < domainLower {
+            clampedX = domainLower
+        } else if x > domainHigher {
+            clampedX = domainHigher
+        } else {
+            clampedX = x
+        }
+        let t = normalize(clampedX.toDouble(), lower: domainLower.toDouble(), higher: domainHigher.toDouble())
+        return interpolator.interpolate(t)
     }
 
     // MARK: - modifier functions
 
-    /// Returns a new scale with the domain set to the span of values you provide.
+    /// Returns a new scale with the interpolator set to the instance you provide.
+    /// - Parameter interpolator: An interpolator instance.
+    /// - Returns: A copy of the scale with the domain values you provide.
+    public func interpolator(_ interpolator: ArrayInterpolator) -> Self {
+        Self(lower: domainLower, higher: domainHigher, reversed: reversed, interpolator: interpolator)
+    }
+
+    /// Returns a new scale with the domain set to the values you provide.
+    /// - Parameters:
+    ///   - lower: The lower bound for the scale's domain.
+    ///   - higher: The upper bound for the scale's domain.
+    /// - Returns: A copy of the scale with the domain values you provide.
+    public func domain(lower: InputType, higher: InputType) -> Self {
+        Self(lower: lower, higher: higher, reversed: reversed, interpolator: interpolator)
+    }
+
+    /// Returns a new scale with the domain set to the values you provide.
+    /// - Parameters:
+    ///   - range: The range to apply as the scale's domain
+    /// - Returns: A copy of the scale with the domain values you provide.
+    public func domain(_ range: ClosedRange<InputType>) -> Self {
+        Self(lower: range.lowerBound, higher: range.upperBound, reversed: reversed, interpolator: interpolator)
+    }
+
+    /// Returns a new scale with the domain set to span the values you provide.
     /// - Parameter values: An array of input values.
-    public func domain(_: [InputType]) -> Self {
-        self
+    public func domain(_ values: [InputType]) -> Self {
+        domain(values, nice: true)
     }
 
-    public var description: String {
-        "A SEQUENTIAL SCALE"
+    /// Returns a new scale with the domain inferred from the list of values you provide.
+    /// - Parameters:
+    ///   - values: The list of values to use to determine the scale's domain.
+    ///   - nice: A Boolean value that indicates whether to expand the domain to visually nice values.
+    /// - Returns: A copy of the scale with the domain values you provide.
+    public func domain(_ values: [InputType], nice: Bool) -> Self {
+        guard let min = values.min(), let max = values.max() else {
+            return self
+        }
+        if values.count == 1 || min == max {
+            if nice {
+                let bottom: Double = 0
+                let top = Double.niceVersion(for: max.toDouble(), trendTowardsZero: false)
+                return domain(lower: InputType.fromDouble(bottom), higher: InputType.fromDouble(top))
+            } else {
+                return domain(lower: 0, higher: max)
+            }
+        } else {
+            if nice {
+                let bottom = Double.niceMinimumValueForRange(min: min.toDouble(), max: max.toDouble())
+                let top = Double.niceVersion(for: max.toDouble(), trendTowardsZero: false)
+                return domain(lower: InputType.fromDouble(bottom), higher: InputType.fromDouble(top))
+            } else {
+                return domain(lower: min, higher: max)
+            }
+        }
     }
 }

Sources/SwiftVizScale/SequentialScale.swift

@@ -17,13 +17,3 @@ func interpolate<T: Real>(_ t: T, lower: T, higher: T) -> T {
     // strict interpolation would require: precondition(t >= 0 && t <= 1)
     lower + (higher - lower) * t
 }
-
-/// A type that provides an interpolated result types between two corresponding instances.
-public protocol Interpolator {
-    /// The type that the interpolator accepts as instances, and returns as an interpolated result.
-    associatedtype OutputType
-    /// Provide an instance that is the interpolated value between two others.
-    /// - Parameter t: A unit value between `0` and `1` that represents the distance between the two values.
-    /// - Returns: An instance of a type that is the interpolated result based on the value you provide.
-    func interpolate(_ t: Double) -> OutputType
-}