img_to_script 1.0.0

data/lib/img_to_script/generators/hex_mask/enhanced.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module Generators
+    module HexMask
+      #
+      # Generates image rendering script using the DRAW/M statement with
+      # the 'enhancements'.
+      #
+      # To save space at the MPO-10 cart, it's possible to replacelong
+      # sequences of repeating chunks with a shorter
+      # (in terms of number of chars required to store the statement) code,
+      # e.g.:
+      #
+      # xxDRAWMFFAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFF
+      # // 43 bytes -- 16 x 'AA'.
+      # xxDRAWMFF:FORI=1TO16:DRAWMAA:NEXTI:DRAWMFF
+      # // 42 bytes -- repeating chunks were replaced with a loop.
+      #
+      # Same principle could be applied to eliminate long sequences of white
+      # pixels, e.g.:
+      # xxDRAWMFF00000000000000000000FF
+      # // 31 bytes -- 10 x '00'.
+      # xxDRAWMFF:DRAWOxxx,yy:DRAWMFF
+      # // 29 bytes -- replaced with a manual shift.
+      #
+      # The algorithm is:
+      # 1. apply RLE to the array of hex chunks (DRAW/M arguments);
+      # 2. loop through the array of run-lengths: take an element (a 'chunk') and
+      #    heck if it's run-length is larger than an estimated value (MIN_REP_CHUNKS
+      #    or MIN_REP_WH_CHUNKS);
+      # 3. if true: add pending chunks to the BASIC code; then append a FOR-NEXT loop or
+      #    DRAW/O. Clear pending chunks array and continue to loop through the array of
+      #    run-lengths.
+      # 4. otherwise: add current chunk to the array of pending chunks;
+      # 5. after the loop: add pending chunks.
+      #
+      class Enhanced < HexMask
+        MIN_REP_CHUNKS = 16
+        MIN_REP_WH_CHUNKS = 9
+
+        private
+
+        def _generate
+          _init_instant_vars
+          _process_rle_image
+          _append_pending_chunks
+        end
+
+        #
+        # Set up initional values for the instant variables.
+        #
+        def _init_instant_vars
+          @x = 0 # It is always = 0, not the x/y_offset. The reason is that
+          @y = 0 # we've already applied offset in the #_prepare_image method.
+
+          @hex_img = _encode_img
+          @rle_hex_img = _encode_hex_img
+
+          @pending_chunks = []
+          @run_length_index = 0
+        end
+
+        #
+        # Loop through the RLE-encoded hex-image.
+        #
+        def _process_rle_image
+          @rle_hex_img.each_with_index do |rle_item, idx|
+            @chunk_count = rle_item.run_length
+            @chunk = rle_item.chunk
+
+            _calc_current_pos
+            _process_chunk(idx)
+          end
+        end
+
+        #
+        # Choose action for a current chunk depending on its run-length
+        # and its color hex value (white or non-white).
+        #
+        # @param [Integer] idx
+        #   Index of the element in the RLE array.
+        #
+        def _process_chunk(idx)
+          if @chunk_count >= MIN_REP_WH_CHUNKS && @chunk == "00"
+            _process_white_segments(idx)
+          elsif @chunk_count >= MIN_REP_CHUNKS && @chunk != "00"
+            _process_non_white_segments
+          else
+            _upd_pending_chunks
+            _upd_rle_index
+          end
+        end
+
+        #
+        # Run-length encoding of the @hex_img.
+        #
+        # @return [Array<RunLengthEncodingRb::RLEElement>]
+        #
+        def _encode_hex_img
+          RunLengthEncodingRb.encode(@hex_img)
+        end
+
+        #
+        # Calculate current (X, Y) position.
+        #
+        def _calc_current_pos
+          @y += @chunk_count
+          return unless @y > @scr_height - 1
+
+          # Reached the vertical end of the screen - re-calculate position:
+          div_res = @y.div(@scr_height)
+          @x += CHUNK_WIDTH * div_res
+          @y = @y.remainder(@scr_height)
+        end
+
+        def _upd_rle_index
+          @run_length_index += @chunk_count
+        end
+
+        def _clr_pending_chunks
+          @pending_chunks = []
+        end
+
+        #
+        # Replace long sequences of repeating non-white chunks with a shorter FOR-NEXT loop.
+        #
+        def _process_non_white_segments
+          _append_pending_chunks
+          _clr_pending_chunks
+
+          _append_start_loop(@chunk_count)
+          _append_hex_values(Array(@chunk))
+          _append_end_loop
+
+          _upd_rle_index
+        end
+
+        def _append_hex_values(hex_values)
+          @tokens.append(
+            AbstractToken::DrawChunkByHexValue.new(
+              hex_values: hex_values
+            )
+          )
+        end
+
+        def _append_start_loop(end_value)
+          @tokens.append(
+            AbstractToken::LoopBegin.new(
+              var_name: LOOP_VAR,
+              start_value: 1,
+              end_value: end_value
+            )
+          )
+        end
+
+        def _append_end_loop
+          @tokens.append(
+            AbstractToken::LoopEnd.new(
+              var_name: LOOP_VAR
+            )
+          )
+        end
+
+        def _append_move_point(x, y)
+          @tokens.append(
+            AbstractToken::MovePointToAbsCoords.new(
+              x: x,
+              y: y
+            )
+          )
+        end
+
+        #
+        # Replace long sequences of white chunks (0x00) with a shorter manual shift of the (X, Y) point.
+        #
+        # @param [Integer] idx
+        #   Index of the element in the RLE array.
+        #
+        def _process_white_segments(idx)
+          # If white segments are the last part of the image,
+          # we don't need to store them in the BASIC script at all
+          return if idx == @rle_hex_img.length - 1
+
+          _append_pending_chunks
+          _clr_pending_chunks
+
+          _append_move_point(@x, @y)
+
+          _upd_rle_index
+        end
+
+        #
+        # Append accumulated pending chunks to the tokens array.
+        #
+        def _append_pending_chunks
+          return if @pending_chunks == []
+
+          _append_hex_values(@pending_chunks)
+        end
+
+        #
+        # Update array of the pending chunks.
+        #
+        def _upd_pending_chunks
+          @pending_chunks.concat _current_pending_chunks
+        end
+
+        #
+        # Retun chunks that are pending at the current itteration.
+        #
+        # @return [Array<String>]
+        #
+        def _current_pending_chunks
+          @hex_img.slice(@run_length_index, @chunk_count)
+        end
+      end
+    end
+  end
+end

data/lib/img_to_script/generators/hex_mask/hex_mask.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module Generators
+    module HexMask
+      #
+      # Base class for the hex-mask-based generators.
+      #
+      class HexMask < Generator
+        CHUNK_WIDTH = 8
+
+        private
+
+        #
+        # Encode a binary image to a hex-mask encoded image.
+        #
+        # @return [Array<String>] hex_img
+        #   An encoded image, represented as an array of hex-chunks.
+        #
+        def _encode_img
+          image = _prepare_image
+
+          hex_img = []
+
+          (0...image.width).step(CHUNK_WIDTH).each do |x|
+            (0...image.height).each do |y|
+              chunk = _grab_chunk(image, x, y)
+              hex_img.push(_bin_to_hex(chunk))
+            end
+          end
+
+          hex_img
+        end
+
+        #
+        # Prepare the image:
+        #   1. ensure that image width is divisible by 8 (CHUNK_WIDTH);
+        #   2. ensure that image height is equal to @scr_height;
+        #   3. offset the image according to the provided @x_offset / @y_offset.
+        #
+        # Steps 1 & 2 are required by the DRAW/M statement's algorithm.
+        #
+        def _prepare_image
+          @image.extent(_new_width,
+                        @scr_height,
+                        @x_offset * -1,
+                        @y_offset * -1)
+        end
+
+        #
+        # Calculate new width for the image.
+        #
+        # The algorithm of the DRAW/M statement requires that image width should
+        # be divisible by 8 (CHUNK_WIDTH). If the image doesn't comply with this
+        # condition, it is required to extend the image width to a nearlest number
+        # n: n.remainder(CHUNK_WIDTH) == 0.
+        #
+        # @return [Integer]
+        #   New width.
+        #
+        def _new_width
+          width = ((@image.width + @x_offset) / CHUNK_WIDTH.to_f).ceil * CHUNK_WIDTH
+          width.clamp(CHUNK_WIDTH, @scr_width)
+        end
+
+        #
+        # Grab a 8 x 1 rectangle from the image and convert its pixels to a binary string representation.
+        #
+        # @param [Magick::Image, Magick::BinMagick::Image] image
+        #
+        # @param [Integer] x, y
+        #   A current X, Y position at the image.
+        #
+        # @return [String]
+        #   An 8-character string of 0's and 1's. Example: "11110011"
+        #
+        def _grab_chunk(image, x, y)
+          chunk_width = CHUNK_WIDTH
+          chunk_heigth = 1
+          pixels = image.get_pixels(x, y, chunk_width, chunk_heigth)
+
+          pixels.map { |pixel| pixel.to_color == "black" ? 1 : 0 }.join("")
+        end
+
+        #
+        # Convert a string of binary values to a two-digit hex representation.
+        #
+        # Example: "11110011" => "F3"
+        #
+        # @param [String] str
+        #
+        # @return [String]
+        #
+        def _bin_to_hex(str)
+          format("%02x", str.to_i(2)).upcase
+        end
+      end
+    end
+  end
+end

data/lib/img_to_script/generators/hex_mask.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module Generators
+    #
+    # Each 8x1 pixels block of a binary image gets encoded as a hex value.
+    #
+    # The method natively supported only by the Elektronika MK90 BASIC with its
+    # DRAWM statement.
+    #
+    module HexMask; end
+  end
+end

data/lib/img_to_script/generators/run_length_encoding/horizontal.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module Generators
+    module RunLengthEncoding
+      #
+      # RLE - horizontal scanlines.
+      #
+      class Horizontal < RunLengthEncoding
+        private
+
+        def _generate
+          @pixels = @image.get_pixels(0, 0, @image.width, @image.height)
+          _encode_pixels
+          _append_decoder
+        end
+
+        def _append_decoder
+          @image_size = @image.width + @x_offset
+          @segment_size = @image_size - 1
+
+          @major_axis_symbol = X_LBL
+          @minor_axis_symbol = Y_LBL
+
+          @major_axis_value = @x_offset
+
+          @part_line_pattern = _part_line_pattern
+          @full_line_pattern = _full_line_pattern
+
+          super
+        end
+
+        #
+        # Part-length line, i.e. a line that fills only
+        # a part of the scan line.
+        #
+        # Formatted for the horizontal scan lines.
+        #
+        def _part_line_pattern
+          AbstractToken::DrawLineByAbsCoords.new(
+            x0: X_LBL,
+            y0: Y_LBL,
+            x1: _x1_expression,
+            y1: Y_LBL
+          )
+        end
+
+        #
+        # Expression to evaluate x1 point.
+        #
+        def _x1_expression
+          AbstractToken::MathSub.new(
+            left: AbstractToken::MathAdd.new(
+              left: X_LBL,
+              right: READ_VAR
+            ),
+            right: 1
+          )
+        end
+
+        #
+        # Full-length line pattern, i.e. a line that fills
+        # the whole scan line.
+        #
+        # Formatted for the horizontal scan lines.
+        #
+        def _full_line_pattern
+          AbstractToken::DrawLineByAbsCoords.new(
+            x0: X_LBL,
+            y0: Y_LBL,
+            x1: @segment_size,
+            y1: Y_LBL
+          )
+        end
+      end
+    end
+  end
+end

data/lib/img_to_script/generators/run_length_encoding/run_length_encoding.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module ImgToScript
+  module Generators
+    module RunLengthEncoding
+      #
+      # Base class for the RLE-based script generators.
+      #
+      class RunLengthEncoding < Generator
+        private
+
+        #
+        # Encode pixels into the RLE data.
+        #
+        def _encode_pixels
+          @run_length_data = RunLengthEncodingRb.encode(@pixels)
+          run_lengths = []
+
+          encode = lambda { |count:, pixel:|
+            count = -count if pixel.to_color == "white"
+            run_lengths.push(count.to_s)
+          }
+
+          @run_length_data.each { |e| encode.call(pixel: e.chunk, count: e.run_length) }
+
+          _append_data(run_lengths)
+        end
+
+        def _append_data(arr)
+          @tokens.append(
+            AbstractToken::DataStore.new(
+              data: arr,
+              require_nl: true
+            )
+          )
+        end
+
+        #
+        # Append RLE decoder procedure afther the DATA sequence.
+        #
+        def _append_decoder
+          _dec_line01
+          _dec_line02
+          _dec_line03
+          _dec_line04
+          _dec_line05
+          _dec_line06
+        end
+
+        #
+        # 1-st line of the decoder procedure.
+        #
+        # In this line the X & Y variables are defined. The X and Y variables
+        # are used to keep track of the current position on the screen.
+        #
+        # Then the main loop starts. The loop iterates over each pixel value
+        # (represented by the variable READ_VAR) in the input data and translates
+        # the RLE-encoded values into the "draw a line" commands that draw lines
+        # on the screen.
+        #
+        def _dec_line01
+          _init_x
+          _init_y
+          _start_loop
+          _read_value
+        end
+
+        #
+        # 2-nd line of the decoder procedure.
+        #
+        # The IF statement is used to check cases where the line would extend
+        # beyond the bounds of the image/screen. In this case the program jumps
+        # to the 5-th line (3 lines down from the current line) of the decoder,
+        # that handles this edge case.
+        #
+        def _dec_line02
+          expression = AbstractToken::MathGreaterThan.new(
+            left: _sum_of_current_point_and_length,
+            right: @segment_size
+          )
+
+          @tokens.append(
+            AbstractToken::IfCondition.new(
+              expression: expression,
+              consequent: CurrentLinePlaceholder.new(3),
+              require_nl: true
+            )
+          )
+        end
+
+        #
+        # 3-rd line of the decoder procedure.
+        #
+        # Draws a line if S is a positive number. Positive numbers represent
+        # black pixels. Negative numbers represent white pixels.
+        #
+        def _dec_line03
+          @tokens.append(
+            AbstractToken::IfCondition.new(
+              expression: _read_var_positive,
+              consequent: @part_line_pattern,
+              require_nl: true
+            )
+          )
+        end
+
+        #
+        # 4-th line of the decoder procedure.
+        #
+        # Updates major axis position. Ends the main loop. Jumps to the end
+        # of the program.
+        #
+        def _dec_line04
+          _update_current_point
+          _end_loop
+          _jump_to_the_end
+        end
+
+        #
+        # 5-th line of the decoder procedure.
+        #
+        # This part handles cases where the line would extend beyond the
+        # bounds of the image/screen. It draws a line from the current
+        # position up to the end of the image/screen.
+        #
+        def _dec_line05
+          @tokens.append(
+            AbstractToken::IfCondition.new(
+              expression: _read_var_positive,
+              consequent: @full_line_pattern,
+              require_nl: true
+            )
+          )
+        end
+
+        #
+        # 6-th line of the decoder procedure.
+        #
+        # This part handles cases where the line would extend beyond the
+        # bounds of the image/screen. It updates the current position on
+        # the screen and the run-length value. When it jumps back to the
+        # line length check (2nd line of the decoder).
+        #
+        def _dec_line06
+          _increment_minor_axis
+          _update_read_variable
+          _reset_major_axis
+          _jump_to_length_check
+        end
+
+        def _read_var_positive
+          AbstractToken::MathGreaterThan.new(
+            left: READ_VAR,
+            right: 0
+          )
+        end
+
+        def _init_x
+          @tokens.append(
+            AbstractToken::AssignValue.new(
+              left: X_LBL,
+              right: @x_offset,
+              require_nl: true
+            )
+          )
+        end
+
+        def _init_y
+          @tokens.append(
+            AbstractToken::AssignValue.new(
+              left: Y_LBL,
+              right: @y_offset
+            )
+          )
+        end
+
+        def _start_loop
+          @tokens.append(
+            AbstractToken::LoopBegin.new(
+              var_name: LOOP_VAR,
+              start_value: 1,
+              end_value: @run_length_data.length
+            )
+          )
+        end
+
+        def _read_value
+          @tokens.append(
+            AbstractToken::DataRead.new(
+              var_list: READ_VAR
+            )
+          )
+        end
+
+        def _abs_length_value
+          AbstractToken::AbsFunc.new(
+            expression: READ_VAR
+          )
+        end
+
+        def _sum_of_current_point_and_length
+          AbstractToken::MathAdd.new(
+            left: _abs_length_value,
+            right: @major_axis_symbol
+          )
+        end
+
+        def _update_current_point
+          @tokens.append(
+            AbstractToken::AssignValue.new(
+              left: @major_axis_symbol,
+              right: _sum_of_current_point_and_length,
+              require_nl: true
+            )
+          )
+        end
+
+        def _end_loop
+          @tokens.append(
+            AbstractToken::LoopEnd.new(
+              var_name: LOOP_VAR
+            )
+          )
+        end
+
+        def _jump_to_the_end
+          @tokens.append(
+            AbstractToken::GoTo.new(
+              line: CurrentLinePlaceholder.new(3)
+            )
+          )
+        end
+
+        def _sign_func
+          AbstractToken::SignFunc.new(
+            expression: READ_VAR
+          )
+        end
+
+        def _increment_minor_axis
+          @tokens.append(
+            AbstractToken::AssignValue.new(
+              left: @minor_axis_symbol,
+              right: AbstractToken::MathAdd.new(
+                left: @minor_axis_symbol,
+                right: 1
+              ),
+              require_nl: true
+            )
+          )
+        end
+
+        def _reset_major_axis
+          @tokens.append(
+            AbstractToken::AssignValue.new(
+              left: @major_axis_symbol,
+              right: @major_axis_value
+            )
+          )
+        end
+
+        def _jump_to_length_check
+          @tokens.append(
+            AbstractToken::GoTo.new(
+              line: CurrentLinePlaceholder.new(-4)
+            )
+          )
+        end
+
+        def _sum_token
+          AbstractToken::MathAdd.new(
+            left: _abs_length_value,
+            right: @major_axis_symbol
+          )
+        end
+
+        def _sub_token
+          AbstractToken::MathSub.new(
+            left: _sum_token,
+            right: @image_size
+          )
+        end
+
+        def _mult_token
+          AbstractToken::MathMult.new(
+            left: AbstractToken::Parentheses.new(
+              expression: _sub_token
+            ),
+            right: _sign_func
+          )
+        end
+
+        def _update_read_variable
+          @tokens.append(
+            AbstractToken::AssignValue.new(
+              left: READ_VAR,
+              right: _mult_token
+            )
+          )
+        end
+      end
+    end
+  end
+end