usps_flags 0.1.17

data/README.md

@@ -0,0 +1,136 @@
+# United States Power Squadrons® Flag Generator
+
+[![Gem Version](https://badge.fury.io/rb/usps_flags.svg)](https://badge.fury.io/rb/usps_flags)
+[![Build Status](https://travis-ci.org/jfiander/usps-flags.svg)](https://travis-ci.org/jfiander/usps-flags)
+[![Coverage Status](https://coveralls.io/repos/github/jfiander/usps-flags/badge.svg?branch=master)](https://coveralls.io/github/jfiander/usps-flags?branch=master)
+
+This gem allows you to generate precise SVG and PNG flag images based on official specifications.
+
+## Installation
+
+### Rails
+
+Add to your Gemfile:
+```ruby
+gem 'usps_flags'
+```
+
+Create the file `config/initializers/usps_flags.rb`:
+```ruby
+USPSFlags::Config.flags_dir "#{Rails.root}/app/assets/images/flags"
+```
+
+### Other
+
+Run `gem install usps_flags`.
+
+Run `require 'usps_flags'` then `USPSFlags::Config.flags_dir "path/to/flags/dir"` to specify where to output all generated files and logs. (Otherwise, will default to `/output` in the gem directory.)
+
+## Available flags
+
+- US Ensign
+- USPS Ensign
+- USPS Ensign Wheel logo
+- Officer flags
+- Officer insignia
+- Official pennants
+
+## Generation
+
+### All files
+
+To generate all static files, run:
+```ruby
+USPSFlags::Generate.all svg: true, png: true, zips: true
+```
+
+- Boolean arguments specify whether to process that set of files.
+
+### Zip archives
+
+To re-generate zip files from current static files, run:
+```ruby
+USPSFlags::Generate.zips svg: true, png: true
+```
+
+- Boolean arguments specify whether to process that set of files.
+
+### Individual files
+
+To generate an individual SVG file, run:
+```ruby
+USPSFlags::Generate.get "flag", outfile: nil, scale: nil, field: true
+```
+
+- `outfile` specifies where to save the file. If left as `nil`, this method will `puts` the generated SVG. Either way, the SVG code is returned.
+- `scale` is a divisor scaling factor – the larger it is, the smaller the resulting SVG will be rendered. Accepted values are floats between 0 and 1, and integers above that.
+- `field` specifies whether to render the field of a flag, or to only render the insignia. Setting this to `false` will invert some colors for visibility.
+
+### Trident spec sheet
+
+To generate the trident spec sheet, run:
+```ruby
+USPSFlags::Generate.spec outfile: nil, scale: nil, fly: 24, unit: "in"
+```
+
+- `outfile` specifies where to save the file. If left as `nil`, this method will `puts` the generated SVG. Either way, the SVG code is returned.
+- `scale` is a divisor scaling factor – the larger it is, the smaller the resulting SVG will be rendered. Accepted values are floats between 0 and 1, and integers above that.
+- `fly` specifies the custom fly measurement to scale all trident labels to.
+- `unit` specifies the custom fly measurement unit to append to all trident labels.
+
+### Convert SVG to PNG
+
+To convert SVG data to a PNG image, run:
+```ruby
+USPSFlags::Generate.png svg_data, outfile: nil, trim: false
+
+# USPSFlags::Generate.png File.read("path/to/svg_image.svg"), outfile: "path/to/output.png", trim: false
+# USPSFlags::Generate.png USPSFlags::Generate.get("LtC"), outfile: "path/to/output.png", trim: true
+```
+
+- `outfile` is required, and specifies where to save the file.
+- `trim` specifies whether to trim blank space from around the image. (This is ideal for generating insignia.)
+
+## Building
+
+You can also build individual flags using the following DSL:
+
+```ruby
+f = USPSFlags.new do
+  type "LtC"
+  scale 3
+  field false
+  trim true
+  svg_file "/path/to/svg/output.svg"
+  png_file "/path/to/png/output.png"
+end
+
+f.svg # Generate SVG file
+f.png # Generate PNG file
+```
+
+- Calling any DSL method without argument, or with `nil` as argument will return the current value.
+- You can explicitly set `svg_file` to `""` to suppress printing the SVG content to console/log.
+- Calling `.png` requires `png_file` to be set.
+
+## Security
+
+This gem is cryptographically signed. To be sure the gem code hasn’t been tampered with:
+
+Add my public key as a trusted certificate:
+
+```sh
+gem cert --add <(curl -Ls https://raw.github.com/jfiander/usps-flags/master/certs/jfiander.pem)
+```
+
+Then install the gem securely:
+
+```sh
+gem install usps_flags -P HighSecurity
+```
+
+## License
+
+Actual images generated (other than the US Ensign) are Copyright © United States Power Squadrons.
+
+This gem is released under the [GPLv3](https://raw.github.com/jfiander/usps-flags/master/LICENSE).

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task default: :spec
+task test: :spec

data/certs/jfiander.pem

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDcDCCAligAwIBAgIBATANBgkqhkiG9w0BAQUFADA/MQ8wDQYDVQQDDAZqdWxp
+YW4xFzAVBgoJkiaJk/IsZAEZFgdmaWFuZGVyMRMwEQYKCZImiZPyLGQBGRYDb25l
+MB4XDTE3MTAxNzIwMzYwNVoXDTE4MTAxNzIwMzYwNVowPzEPMA0GA1UEAwwGanVs
+aWFuMRcwFQYKCZImiZPyLGQBGRYHZmlhbmRlcjETMBEGCgmSJomT8ixkARkWA29u
+ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKgyweLKJcXOZUJ/Y/fb
+IjGIQzFgi0UUbIxc6BRP3BYCAr7MpflEq3sYaVsECs0ZyM27zLpyDN0oW73Wby6k
+jaik/yBcsDMvrl58+6mjHnB3yIuk0BbEfQaijgMBzW2p0hToocMToMXigwZOGe4e
+kPTAO6yTIIYLhhjWALA+nURCBcCNI8d1YAIjiEuF1lCr4pnV4aAq8tPBVrz7a8Fg
+WpeLe0V1Blhkg9BDzNUmSrDxDxitO8oA5+A0z9Wm1xn8cJfn50103813SEK8gaXV
+eb/zLRa/CNnTzQ8xUrySd10b1auLnKduXgewBhINcWYjDOT/C1FCjxpK5F6buJ6S
+1ukCAwEAAaN3MHUwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0OBBYEFI/F
+wfSc4YJ3gO9EnkvjGcT6fE3WMB0GA1UdEQQWMBSBEmp1bGlhbkBmaWFuZGVyLm9u
+ZTAdBgNVHRIEFjAUgRJqdWxpYW5AZmlhbmRlci5vbmUwDQYJKoZIhvcNAQEFBQAD
+ggEBAHddpCbrFKtf02u/4MPzRQQO+uTP9vlbNDxseQsMvpjIIzMjJzANGBqPeI+V
+HCjLEnKtnUi9br+RqjtQWWc2jGBdZwrlhOFglKUcTVn60ZvBNrByUj8PeBHQR3U2
+vEKSi1v2i/jlVVvrk+9z4DZ4QdrfARBcPCZhUSZcZBsDbnzjMeX6lhoknnqKn/oi
+op1Z8vhtFmvxNk4UfHMG1bdUoxl6DDXKfodqWM//9mARZwSyVX9oV7snFP0nKUaD
+3YzYAc+kXfD7kkzA2NMvLT6Q1v03qQyIZ8BS8SNk5wLGAdLM+IravFDLEs448fjz
+lEAU0RHLFVbE+CXW6makIlWGHR0=
+-----END CERTIFICATE-----

data/lib/rational.rb

@@ -0,0 +1,37 @@
+# Monkey patch to add some formatting methods to Rational.
+# 
+# @author Julian Fiander
+# @since 0.1.5
+class Rational
+  # Converts Rational to String
+  #
+  # If Rational is an improper fraction, removes the integer part to convert to a mixed fraction.
+  #
+  # @example Mixed fraction
+  #   Rational(4,3).to_simplified_s #=> "1 1/3"
+  # @return [String] If less than 1, fraction. If greater than 1, a mixed fraction.
+  def to_simplified_s
+    if self < 1
+      to_s
+    else
+      truncated = self.truncate
+      "#{truncated} #{self - truncated}"
+    end
+  end
+
+  # Converts Rational to Array
+  #
+  # If Rational is an improper fraction, removes the integer part to convert to a mixed fraction.
+  #
+  # @example Mixed fraction
+  #   Rational(4,3).to_simplified_a #=> [1, Rational(1,3)]
+  # @return [Array] If less than 1, fraction. If greater than 1, a mixed fraction.
+  def to_simplified_a
+    if self < 1
+      to_s
+    else
+      truncated = self.truncate
+      [truncated, (self - truncated)]
+    end
+  end
+end

data/lib/usps_flags.rb

@@ -0,0 +1,140 @@
+# Base class for the namespace. Provides a constructor DSL.
+# 
+# @author Julian Fiander
+# @since 0.1.5
+class USPSFlags
+  require 'fileutils'
+  require 'zip'
+  require 'mini_magick'
+  require 'rational'
+  require 'usps_flags/config'
+  require 'usps_flags/helpers'
+  require 'usps_flags/core'
+  require 'usps_flags/generate'
+
+  # Constructor for individual flags.
+  #
+  # @example Generate insignia at default scale for Lt/C
+  #  f = USPSFlags.new do
+  #    type "LtC"
+  #    scale 3
+  #    field false
+  #    trim true
+  #    svg_file "/path/to/svg/output.svg"
+  #    png_file "/path/to/png/output.png"
+  #  end
+  #
+  #  f.svg #=> Generates SVG file at "/path/to/svg/output.svg"
+  #  f.png #=> Generates PNG file at "/path/to/png/output.png"
+  def initialize(&block)
+    @type = nil
+    @svg_file = nil
+    @png_file = nil
+    @scale = nil
+    @field = nil
+    @trim = nil
+    instance_eval(&block) if block_given?
+  end
+
+  # Constructor accessor for the flag type.
+  #
+  # @param [String] type If set, updates the constructor's flag type.
+  # @return [String] Returns the current (or updated) flag type.
+  def type(string = nil)
+    if string.nil?
+      @type
+    else
+      @type = string
+      self
+    end
+  end
+
+  # Constructor accessor for the SVG file output path.
+  #
+  # @param [String] svg_file If set, updates the constructor's SVG file output path.
+  # @return [String] Returns the current (or updated) SVG file output path.
+  def svg_file(string = nil)
+    if string.nil?
+      @svg_file
+    else
+      @svg_file = string
+      self
+    end
+  end
+
+  # Constructor accessor for the PNG file output path.
+  #
+  # @param [String] png_file If set, updates the constructor's PNG file output path.
+  # @return [String] Returns the current (or updated) PNG file output path.
+  def png_file(string = nil)
+    if string.nil?
+      @png_file
+    else
+      @png_file = string
+      self
+    end
+  end
+
+  # Constructor accessor for the image scale divisor factor.
+  #
+  # Available options are Float between 0 and 1, or Integer above 1.
+  #
+  # @param [Integer, Float] scale If set, updates the constructor's scale divisor factor.
+  # @return [Integer, Float] Returns the current (or updated) scaling factor.
+  def scale(num = nil)
+    if num.nil?
+      @scale
+    else
+      @scale = num
+      self
+    end
+  end
+
+  # Constructor accessor for whether to generate the flag field (including any border).
+  #
+  # @param [Boolean] field If set, updates the constructor's field setting.
+  # @return [Boolean] Returns the current (or updated) setting.
+  def field(bool = nil)
+    if bool.nil?
+      @field
+    else
+      @field = bool
+      self
+    end
+  end
+
+  # Constructor accessor for whether to trim the generated PNG file of excess transparency.
+  #
+  # @param [Boolean] trim If set, updates the constructor's trim setting.
+  # @return [String] Returns the current (or updated) setting.
+  def trim(bool = nil)
+    if bool.nil?
+      @trim
+    else
+      @trim = bool
+      self
+    end
+  end
+
+  # Generates the constructed file as SVG.
+  #
+  # @return [String] Returns the SVG file output path, or the svg data if no path was specified.
+  def svg
+    svg = USPSFlags::Generate.get(self.type, outfile: self.svg_file, scale: self.scale, field: self.field)
+    (self.svg_file.nil? || self.svg_file == "") ? svg : self.svg_file
+  end
+
+  # Generates the constructed file as PNG.
+  #
+  # Requires the constructor to have a value for png_file.
+  #
+  # @return [String] Returns the SVG file output path.
+  def png
+    raise "Error: png_file must be set." if self.png_file.nil?
+    svg_file_storage = self.svg_file
+    self.svg_file ""
+    USPSFlags::Generate.png(self.svg, outfile: self.png_file, trim: self.trim)
+    self.svg_file svg_file_storage
+    self.png_file
+  end
+end

data/lib/usps_flags/config.rb

@@ -0,0 +1,115 @@
+# Container class for configuration values.
+class USPSFlags::Config
+  BLUE ||= "#041E42" # Old Glory Blue
+  RED ||= "#BF0D3E"  # Old Glory Red
+
+  # Base measurements for most flags, before scaling
+  BASE_FLY ||= 3072
+  BASE_HOIST ||= BASE_FLY*2/3
+  FRACTION_SCALE ||= 85
+
+  @@flags_dir ||= "#{File.dirname(__dir__)}/output"
+  @@use_larger_tridents ||= true
+
+  # Accessor for the directory for storing generated flags.
+  #
+  # @param [String] init If set, updates the path to the directory for storing generated flags.
+  # @param [Boolean] reset Delete all files in the specified directory if found.
+  # @example Update flag storage directory
+  #   # Rails.root => "/path/to"
+  #   USPSFlags::Config.flags_dir "#{Rails.root}/app/assets/images/flags" #=> "/path/to/app/assets/images/flags"
+  # @example Update flag storage directory that already has some files in it
+  #   # Rails.root => "/path/to"
+  #   USPSFlags::Config.flags_dir "#{Rails.root}/app/assets/images/flags", reset: true #=> "/path/to/app/assets/images/flags"
+  # @return [String] Returns the current (or updated) path to the flags directory.
+  def self.flags_dir(init = nil, reset: false)
+    unless init.nil?
+      @@flags_dir = init
+      ::FileUtils.rm_rf(USPSFlags::Config.flags_dir) if reset
+      [
+        "#{USPSFlags::Config.flags_dir}/SVG/insignia",
+        "#{USPSFlags::Config.flags_dir}/PNG/insignia",
+        "#{USPSFlags::Config.flags_dir}/ZIP"
+      ].each do |dir|
+        ::FileUtils.mkdir_p(dir)
+      end
+      ::FileUtils.mkdir_p(USPSFlags::Config.log_path) unless defined?(Rails)
+    end
+    @@flags_dir
+  end
+
+  # Alias for the directory to store generated log files.
+  #
+  # @example Rails
+  #   # Rails.root => "/path/to"
+  #   USPSFlags::Config.logs_dir #=> "/path/to/log"
+  #
+  # @example Non-Rails
+  #   USPSFlags::Config.logs_dir #=> "/app/root/log"
+  def self.log_path
+    if defined?(Rails)
+      "#{Rails.root}/log"
+    else
+      log_dir = "#{self.flags_dir}/log"
+      ::FileUtils.mkdir_p(log_dir)
+      log_dir
+    end
+  end
+
+  # Accessor for the boolean of whether to use the larger or smaller trident width.
+  #
+  # @param [Boolean] bool If set to a Boolean, specify whether to use the larger trident width.
+  # @return [Boolean] Returns the current (or updated) setting.
+  def self.use_larger_tridents(bool = nil)
+    # Smaller: 1/2 in width on 24in x 16in field
+    # Larger:  5/8 in width on 24in x 16in field
+    @@use_larger_tridents = bool unless bool.nil? || !([true, false].include?(bool))
+    @@use_larger_tridents 
+  end
+
+  # Base configuration values for trident insignia.
+  #
+  # All other values are derived from these, or directly from the constant sizes.
+  #
+  # @return [Hash] Returns the configuration values for tridents.
+  def self.trident
+    point_height = USPSFlags::Config::BASE_FLY/48*17/8
+    bar_width = USPSFlags::Config::BASE_FLY/48
+    bar_width = bar_width*5/4 if self.use_larger_tridents
+    {
+      height: {
+        s:   USPSFlags::Config::BASE_HOIST/2,
+        d:   USPSFlags::Config::BASE_HOIST*5/8,
+        stf: USPSFlags::Config::BASE_HOIST*3/4,
+        n:   USPSFlags::Config::BASE_HOIST*3/4
+      },
+
+      center_point: BASE_FLY/2,
+
+      width: USPSFlags::Config::BASE_FLY*5/32,
+
+      bar_width: bar_width,
+
+      point_height: point_height,
+
+      main_point_barb: USPSFlags::Config::BASE_HOIST/240,
+
+      crossbar_from_top: USPSFlags::Config::BASE_HOIST/4,
+
+      side_spike_height: USPSFlags::Config::BASE_HOIST/4-point_height-bar_width,
+
+      hash_width: USPSFlags::Config::BASE_FLY*3/32,
+
+      delta_height: USPSFlags::Config::BASE_FLY*2/15,
+      delta_gap_height: self.use_larger_tridents ? USPSFlags::Config::BASE_FLY*14/256 : USPSFlags::Config::BASE_FLY*17/256,
+      delta_gap_width: self.use_larger_tridents ? bar_width*5/4 : bar_width*7/4,
+      delta_width: USPSFlags::Config::BASE_FLY*43/768,
+      delta_from_bottom: USPSFlags::Config::BASE_HOIST*11/64,
+      delta_gap_scale: 0.40,
+      delta_gap_x: USPSFlags::Config::BASE_HOIST*144/128,
+      delta_gap_y: USPSFlags::Config::BASE_HOIST*221/256,
+
+      circle_height_adj: USPSFlags::Config::BASE_FLY/800
+    }
+  end
+end