vissen-output 0.6.1

data/lib/vissen/output/context/cloud.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    module Context
+      # The cloud context imposes no structure on the placement of its elements
+      # but instead accepts coordinates for each individual point.
+      #
+      # == Usage
+      # The following example creates a context with three points, placed on a
+      # straight line.
+      #
+      #   placement = [[0.1, 0.1],
+      #                [0.5, 0.5],
+      #                [0.9, 0.9]]
+      #   context = Cloud.new placement
+      #
+      class Cloud
+        include Context
+
+        # @return [Array<Point>] the points in the context.
+        attr_reader :points
+
+        # @param  points [Array<Point>, Array<Array<Integer>>] the position of
+        #   the points in the context.
+        # @param  width [Float] the width of the context.
+        # @param  height [Float] the height of the context.
+        # @param  args (see Context).
+        def initialize(points, width: 1.0, height: 1.0, **args)
+          super(width, height, **args)
+
+          factor = @width / width
+
+          @points = points.map { |point| Point.from point, scale: factor }
+          freeze
+        end
+
+        # Prevents any more points from being added.
+        #
+        # @return [self]
+        def freeze
+          @points.freeze
+          super
+        end
+
+        # See `Context#point_count`.
+        #
+        # @return [Integer] the number of grid points.
+        def point_count
+          @points.length
+        end
+
+        # @return [Array<Integer>] the x and y coordinates of a point.
+        def position(index)
+          @points[index].position
+        end
+
+        class << self
+          # Randomly places points separated by a minimum distance. Note that
+          # the algorithm is nondeterministic in the time it takes to find the
+          # points.
+          #
+          # Draws a random point from the space of valid coordinates and
+          # calculates the distance to all previously selected points. If the
+          # distances are all greater than the given value the point is accepted
+          # and the process repeats until all points have been found.
+          #
+          # @raise  [RangeError] if distance is too great and the allocation
+          #   algorithm therefore is unlikely to converge.
+          #
+          # @param  point_count [Integer] the number of points to scatter.
+          # @param  width [Numeric] the width of the context.
+          # @param  height [Numeric] the height of the context.
+          # @param  distance [Numeric] the minimum distance between each point.
+          # @param  args (see Context).
+          def scatter(point_count,
+                      width: 1.0,
+                      height: 1.0,
+                      distance: nil,
+                      **args)
+            if distance
+              d2 = (distance**2)
+              raise RangeError if 2 * d2 * point_count > width * height
+            else
+              d2 = (width * height) / (2.0 * point_count)
+            end
+
+            points = place_points point_count,
+                                  position_scrambler(width, height),
+                                  distance_condition(d2)
+
+            new(points, width: width, height: height, **args)
+          end
+
+          private
+
+          # @param  x_max [#to_f] the largest value x is allowed to take.
+          # @param  y_max [#to_f] the largest value y is allowed to take.
+          # @return [Proc] a proc that ranomizes the first and second element of
+          #   the given array.
+          def position_scrambler(x_max, y_max)
+            x_range = 0.0..x_max.to_f
+            y_range = 0.0..y_max.to_f
+
+            proc do |pos|
+              pos[0] = rand x_range
+              pos[1] = rand y_range
+              pos
+            end
+          end
+
+          def place_points(point_count, scrambler, condition)
+            points = Array.new(point_count) { [0.0, 0.0] }
+            points.each_with_index do |point, i|
+              loop do
+                scrambler.call point
+                break if points[0...i].all?(&condition.curry[point])
+              end
+            end
+            points
+          end
+
+          def distance_condition(distance_squared)
+            ->(p, q) { (p[0] - q[0])**2 + (p[1] - q[1])**2 > distance_squared }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vissen/output/context/grid.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    module Context
+      # The grid structure stores the number of rows and columns as well as its
+      # width and height. The dimensions are normalized to fit within a 1x1
+      # square.
+      #
+      # Aspect ratio is defined as width/height. If it is not given each grid
+      # cell is assumed to be square, meaning the aspect_ratio will equal
+      # columns/rows.
+      class Grid
+        include Context
+
+        # @return [Integer] the number of rows in the grid.
+        attr_reader :rows
+
+        # @return [Integer] the number of columns in the grid.
+        attr_reader :columns
+
+        # @param  rows [Integer] the number of rows in the grid.
+        # @param  columns [Integer] the number of columns in the grid.
+        # @param  width [Numeric] (see Context)
+        # @param  height [Numeric] (see Context)
+        # @param  args (see Context)
+        def initialize(rows,
+                       columns,
+                       width: (columns - 1).to_f,
+                       height: (rows - 1).to_f,
+                       **args)
+          raise RangeError if rows <= 0 || columns <= 0
+
+          @rows    = rows
+          @columns = columns
+
+          super(width, height, **args)
+
+          define_position
+        end
+
+        # See `Context#point_count`.
+        #
+        # @return [Integer] the number of grid points.
+        def point_count
+          @rows * @columns
+        end
+
+        # See `Context#index_from`.
+        #
+        # WARNING: no range check is performed.
+        #
+        # @param  row [Integer] the row of the point of interest.
+        # @param  column [Integer] the column of the point of interest.
+        # @return [Integer] the index of a row and column.
+        def index_from(row, column)
+          column * @rows + row
+        end
+
+        # Calculates the row and column of the the point stored at the given
+        # index.
+        #
+        # @param  index [Integer] the index of the point of interest.
+        # @return [Array<Integer>] the row and column of a given index.
+        def row_column_from(index)
+          row    = (index % @rows)
+          column = (index / @rows)
+          [row, column]
+        end
+
+        # Iterates over each point in the grid and yields the index, row and
+        # column.
+        #
+        # @return [Integer] the number of points in the grid.
+        def each_row_and_column
+          return to_enum(__callee__) unless block_given?
+
+          point_count.times { |i| yield(i, *row_column_from(i)) }
+        end
+
+        private
+
+        def define_position
+          # Define #position dynamically based on the
+          # calculated width and height
+          x_factor = @columns == 1 ? 0.0 : width / (@columns - 1)
+          y_factor = @rows == 1 ? 0.0 : height / (@rows - 1)
+
+          # Position
+          #
+          # Returns the x and y coordinates of the grid point at the given
+          # index.
+          define_singleton_method(:position) do |index|
+            [
+              x_factor * (index / @rows),
+              y_factor * (index % @rows)
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vissen/output/context.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    # The output context gives the points that relate to it their position and
+    # color. Contexts can come in different forms and offer different
+    # functionality but they must be able to answer three questions:
+    #
+    # 1. How many points are in the context,
+    # 2. what is the absolute position of each point and
+    # 3. what color palette corresponds to a palette index.
+    #
+    module Context
+      # @return [Float] the normalized width of the context.
+      attr_reader :width
+
+      # @return [Float] the normalized width of the context.
+      attr_reader :height
+
+      # @return [Array<Palette>] the array of palettes used to render the
+      #   context.
+      attr_reader :palettes
+
+      # Output contexts give the two things to the vixels within them: a
+      # position and a color.
+      #
+      # The width and height are always normalized to fit within a 1 x 1 square.
+      #
+      # @param  width [Numeric] the width of the context.
+      # @param  height [Numeric] the height of the context.
+      # @param  palettes [Array<Palette>] the color palettes to use when
+      #   rendering the context.
+      def initialize(width, height, palettes: PALETTES)
+        if width.negative? || height.negative? || (width.zero? && height.zero?)
+          raise RangeError, 'Contexts needs a size in at least one dimension'
+        end
+
+        # Normalize width and height
+        normalizing_factor = 1.0 / [width, height].max
+
+        @width    = width * normalizing_factor
+        @height   = height * normalizing_factor
+        @palettes = palettes
+      end
+
+      # This method must be implemented by any class that includes this module.
+      def point_count
+        raise NotImplementedError
+      end
+
+      # @return [true, false] true if the context has only one dimension.
+      def one_dimensional?
+        @width == 0.0 || @height == 0.0
+      end
+
+      # Allocates, for each grid point, one object of the given class.
+      # Optionally takes a block that is expected to return each new object. The
+      # index of the element is passed to the given block.
+      #
+      # @raise  [ArgumentError] if both a class and a block are given.
+      #
+      # @param  klass [Class] the class of the allocated objects.
+      # @param  block [Proc] the block to call for allocating each object.
+      # @return [Array<klass>] an array of new objects.
+      def alloc_points(klass = nil, &block)
+        if klass
+          raise ArgumentError if block_given?
+          block = proc { klass.new }
+        end
+
+        Array.new(point_count, &block)
+      end
+
+      # Iterates over the context points. The index of the the point is passed
+      # to the given block.
+      #
+      # @return [Enumerator, Integer] an `Enumerator` if no block is given,
+      #   otherwise the number of points that was iterated over.
+      def each
+        point_count.times
+      end
+
+      # This method must be implemented by a class that includes this module and
+      # should return the x and y coordinates of the point with the given index.
+      #
+      # @param  _index [Integer] the index of a point in the context.
+      # @return [Array<Float>] an array containing the x and y coordinates of
+      #   the point associated with the given intex.
+      def position(_index)
+        raise NotImplementedError
+      end
+
+      # Iterates over each point in the grid and yields the point index and x
+      # and y coordinates.
+      #
+      # @return (see #each)
+      def each_position
+        return to_enum(__callee__) unless block_given?
+
+        point_count.times do |index|
+          yield(index, *position(index))
+        end
+      end
+
+      # Context specific method to convert any domain specifc property (like row
+      # and column) to an index. The Cloud module calls this method when
+      # resolving the index given to its #[] method.
+      #
+      # @param  index [Object] the object or objects that are used to refer to
+      #   points in this context.
+      # @return [Integer] the index of the point.
+      def index_from(index)
+        index
+      end
+
+      # This utility method traverses the given target array and calculates for
+      # each corresponding grid point index the squared distance between the
+      # point and the given coordinate.
+      #
+      # @param  x [Numeric] the x coordinate to calculate distances from.
+      # @param  y [Numeric] the y coordinate to calculate distances from.
+      # @param  target [Array<Float>] the target array to populate with
+      #   distances.
+      def distance_squared(x, y, target)
+        target.each_with_index do |_, i|
+          x_i, y_i = position i
+          dx = x_i - x
+          dy = y_i - y
+          target[i] = (dx * dx) + (dy * dy)
+        end
+      end
+    end
+  end
+end

data/lib/vissen/output/context_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    # Context errors occur when two components of the output stack are used
+    # together even though they do not share the same context.
+    class ContextError < Error
+      # @param  msg [String] the error messge.
+      def initialize(msg = 'The context of the given object does not match')
+        super
+      end
+    end
+  end
+end

data/lib/vissen/output/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    # This is the top level output error class and should be subclassed by all
+    # other custom error classes used in this library.
+    class Error < StandardError
+    end
+  end
+end

data/lib/vissen/output/filter/gamma.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    module Filter
+      # Applies gamma correction to the given PixelGrid.
+      class Gamma
+        include Filter
+
+        # @return [Float] the gamma correction value.
+        attr_reader :value
+
+        # @param  args (see Filter)
+        # @param  value [Float] the gamma correction value.
+        def initialize(*args, value: 2.2)
+          super(*args)
+
+          @value = value
+
+          freeze
+        end
+
+        # Applies the filter to the given pixel cloud.
+        #
+        # @see Filter
+        # @param pixel_buffer [PixelBuffer] the pixel buffer to perform the
+        #   filter operation on.
+        def apply(pixel_buffer)
+          pixel_buffer.each do |pixel|
+            pixel.r = pixel.r**@value
+            pixel.g = pixel.g**@value
+            pixel.b = pixel.b**@value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vissen/output/filter/quantizer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    module Filter
+      # Scales and rounds the color components to only take discrete values.
+      class Quantizer
+        include Filter
+
+        # @raise  [RangeError] if steps < 2.
+        # @raise  [ArgumentError] if the range is exclusive and has a floating
+        #   point end value.
+        #
+        # @param  args (see Filter)
+        # @param  steps [Integer] the number of quantized steps.
+        # @param  range [Range] the range in which the quantized values should
+        #   lie.
+        def initialize(*args, steps: 256, range: 0...steps)
+          super(*args)
+
+          raise RangeError if steps < 2
+
+          from = range.begin
+          to   = if range.exclude_end?
+                   raise ArgumentError if range.end.is_a?(Float)
+                   range.end - 1
+                 else
+                   range.end
+                 end
+
+          design_function from, to, steps
+
+          freeze
+        end
+
+        # Applies the filter to the given pixel cloud.
+        #
+        # @see Filter
+        # @param pixel_buffer [PixelBuffer] the pixel Buffer to perform the
+        #   filter operation on.
+        def apply(pixel_buffer)
+          pixel_buffer.each do |pixel|
+            pixel.r = @fn.call pixel.r
+            pixel.g = @fn.call pixel.g
+            pixel.b = @fn.call pixel.b
+          end
+        end
+
+        private
+
+        def design_function(from, to, steps)
+          steps -= 1
+          @fn =
+            if from.zero? && to == steps
+              ->(v) { (v * to).round }
+            else
+              factor = (to - from).to_f / steps
+              ->(v) { from + (v * steps).round * factor }
+            end
+        end
+      end
+    end
+  end
+end

data/lib/vissen/output/filter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    # An output filter is defined as a time invariant operation on a pixel
+    # cloud. Upon initialization the filter is given the output context as a
+    # chance to precompute some results. The rest of the work is done in
+    # `#apply` and should not depend on time.
+    module Filter
+      # @return [Context] the filter context.
+      attr_reader :context
+
+      # @raise  [TypeError] if the context is not a `Context`.
+      #
+      # @param  context [Context] the context within which the filter will be
+      #   applied.
+      def initialize(context)
+        raise TypeError unless context.is_a? Context
+
+        @context = context
+      end
+
+      # This method should apply the filter to the given `PixelBuffer`.
+      #
+      # @raise  NotImplementedError if the method is not implemented in the
+      #   specific `Filter` implementation.
+      #
+      # @param  _pixel_buffer [PixelBuffer] the pixel cloud to which the filter
+      #   should be applied.
+      def apply(_pixel_buffer)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/vissen/output/palette.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    # The Palette is, at its core, a transformation between a position (0..1)
+    # and a color value \\{(0..1) x 3\\}. It can either be continous or be based
+    # on a pre-allocated lookup table.
+    #
+    # == Usage
+    # The following example creates a continuous palette and acesses the color
+    # at index 0.42.
+    #
+    #   palette = Palette.new 0x11998e, 0x38ef7d, label: 'Quepal'
+    #   palette[0.42] => #21BD87
+    #
+    # A discrete palette can also be created by specifying the number of steps
+    # to use.
+    #
+    #   palette = Palette.new 0x11998e, 0x38ef7d, steps: 5
+    #   palette[0.42] => #1BAF8A
+    #
+    class Palette
+      # @return [String, nil] the optional palette label.
+      attr_reader :label
+
+      # @param  colors [Array<Color>, Array<#to_a>] the colors to use in the
+      #   palette.
+      # @param  steps [Integer] the number of discrete palette values. The
+      #   palette will be continuous if nil.
+      # @param  label [String] the optional label to use when identifying the
+      #   palette.
+      def initialize(*colors, steps: nil, label: nil)
+        @colors = colors.map { |c| Color.from(c).freeze }
+        @label  = label
+
+        if steps
+          define_discrete_accessor steps
+        else
+          define_continous_accessor
+        end
+
+        freeze
+      end
+
+      # Prevents both the palette colors and the label from changing.
+      #
+      # @return [self]
+      def freeze
+        @colors.freeze
+        @label.freeze
+
+        super
+      end
+
+      # Discretize the palette into the given number of values. Palettes defined
+      # with a step count are sampled as if they where continuous.
+      #
+      # @param  n [Integer] the number of discrete values to produce.
+      # @return [Array<Color>] an array of colors sampled from the palette.
+      def to_a(n)
+        Array.new(n) { |i| color_at(i.to_f / (n - 1)).freeze }
+      end
+
+      # Example output:
+      #   "#42BEAF -> #020180 (rainbow)"
+      #
+      # @return [String] a string representation of the palette made up of the
+      #   palette colors as well as the (optional) label.
+      def inspect
+        @colors.map(&:inspect).join(' -> ').tap do |base|
+          break "#{base} (#{@label})" if @label
+        end
+      end
+
+      private
+
+      def define_discrete_accessor(steps)
+        @palette = to_a steps
+        define_singleton_method :[] do |index|
+          index = if index >= 1.0 then @palette.length - 1
+                  elsif index < 0.0 then 0
+                  else (index * (@palette.length - 1)).floor
+                  end
+
+          @palette[index]
+        end
+      end
+
+      def define_continous_accessor
+        define_singleton_method(:[]) { |pos| color_at pos }
+      end
+
+      def color_bin(pos)
+        num_bins     = (@colors.length - 1)
+        bin          = (pos * num_bins).floor
+        mixing_ratio = pos * num_bins - bin
+
+        [bin, mixing_ratio]
+      end
+
+      def color_at(pos)
+        return @colors[0]  if pos <= 0
+        return @colors[-1] if pos >= 1
+
+        # Find the two colors we are between
+        bin, r = color_bin pos
+        a, b = @colors[bin, 2]
+        a.mix_with b, r
+      end
+    end
+  end
+end

data/lib/vissen/output/palettes.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    # Default palette collection.
+    PALETTES = {
+      'Argon'      => [0x03001e, 0x7303c0, 0xec38bc, 0xfdeff9],
+      'Red Sunset' => [0x355c7d, 0x6c5b7b, 0xc06c84],
+      'Quepal'     => [0x11998e, 0x38ef7d]
+    }.map { |l, c| Palette.new(*c, label: l) }.freeze
+  end
+end

data/lib/vissen/output/pixel.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Output
+    # The `Pixel` object is used by the `PixelBuffer` to store the colors of its
+    # points.
+    #
+    # TODO: How do we want the pixel to saturate? When written or when read?
+    class Pixel < Color
+      # Reset the pixel color to black (0, 0, 0).
+      #
+      # @return [self]
+      def clear!
+        self.r = 0
+        self.g = 0
+        self.b = 0
+        self
+      end
+
+      # @return [String] a string representation of the pixel.
+      def inspect
+        format '(%.1f, %.1f, %.1f)', r, g, b
+      end
+    end
+  end
+end