Dimsome

Dimsome is a collection of 2d arithmetic convenience methods and classes, such Point or Rect. For use with RubyMotion targeting AppleOS (ios, macos, tvos, etc), the methods are added to the Foundation SDK types CGPoint (ATSPoint for macos), CGSize and CGRect.

Please note: much of the project is in the fairly early stages. Most of the methods themselves I've been using in one way or another for well over a year but some garbling may have happened as I hacked things for different ruby platforms.

Also: heartfelt thanks to the author-contributors of the Geomotion gem (github repo). I had been picking at what became Dimsome for half a year before I stumbled on Geomotion. It's ios-only and I needed osx/bottom-left origin for SpriteKit work but it's a mature, working gem (with tests!) along very similar lines and gave me lots to play with while I settled what I really wanted. And in fact, ios-natural screen coordinates is something Dimsome (almost) totally doesn't do, so if that's what you need, go Geomotion.

Included in this repo:

• Dimsome code
• Gemspec to build a gem for RubyMotion or Ruby
• (RubyMotion) basic ios and osx app code (ie Rakefile, AppDelegate, etc), for experimenting with Dimsome in the RubyMotion REPL
• (DragonRuby-GTK) Ruby script dragonruby_cat.rb to cat the necessary Dimsome code plus tidbits into a single file for adding to DragonRuby-GTK projects (DragonRuby-GTK doesn't handle gems yet)
• (DragonRuby-GTK) Porkbelly, a Bacon/MacBacon testing module derivative for running the test files in DragonRuby-GTK.
• spec/ directory of test files to be run with RubyMotion's built-in Bacon, RSpec for Ruby, Porkbelly for DragonRuby-GTK (or Ruby, with run_porkbelly.rb, in the dragon_dimsome/ directory).
• info/ directory of further documentation (setting doc/ aside currently, for exploring rdoc/yard generated docs)
• samples/ directory containing dragon_dimsome_demo project for running the tests
• LICENSE, this README.md

Good to know:

• Dimsome runs in RubyMotion for AppleOS (no Android yet), Ruby (ie MRI-ish) and DragonRuby-GTK (ie mruby-ish)
• I'm overwhelmingly focussed on tools for sketching/experimenting, so Dimsome is not at all optimized for anything but easy typing and reading. Could be later. We'll see.
• all methods but the simplest setters return a new not modified object.
• ALL coordinates are relative to a bottom-left origin, for all targets.
• rect is sized-rect, not kitty-rect (which is to say, an origin point and a size, not origin and farpoint).
• there are tests and they run on all targets (see Testing, DragonRuby-GTK_notes). There need to be more.
• the Grid and Twig classes included here are trivial and undocumented and probably belong somewhere else but I experiment with them a lot and I don't know what else to do with them yet.
• The name 'Dimsome' is just my shorthand for 'arithmetic for SOME DIMensionS'. In hindsight, I think it might've been a mistake because it sounds exactly like 'dimsum' and now arithmetic always makes me hungry. Sigh.

Jump to topic:

• Getting Started
• Initializers and Inspectors
• Classes Dim2d, Point, Size
• Class Rect
• Kludgey IOS-oriented methods
• API Cheatsheet
• Dimsome Testing and Porkbelly
• To Do/Buglist

Installation

To build the gem:

gem build dimsome.gemspec

To install the (locally-built or downloaded) gem:

gem install ./dimsome-0.2.0.gem

DragonRuby-GTK doesn't currently support gem loading, so 'dragon_dimsome.rb' is created by a little ruby script dragonruby_cat.rb that cats all the necessary code into a single ruby file.

To install for DragonRuby-GTK, copy the dragon_dimsome/ directory into your project

Usage

RubyMotion

To use in a RubyMotion app, include in the Gemfile:

gem 'dimsome'

and then bundle install or run using bundle exec rake.

To run the basic Dimsome app to experiment in the RubyMotion REPL on osx:

bundle exec rake

or on ios:

ios=true bundle exec rake

(one Rakefile here to launch in either ios or osx)

Ruby

To use in Ruby (in a program or Pry, for instance):

require 'dimsome'

DragonRuby-GTK

To use in DragonRuby-GTK, add in your main.rb:

require 'dragon_dimsome/dragon_dimsome.rb'

The samples/ project dragon_dimsome_demo is for running the test files (with the Porkbelly testing module) and shows the basic pattern.

Getting Started

Dimsome was initially created for use with RubyMotion and the AppleOS Foundation data types CGPoint, CGSize and CGRect (which are Objective-C structs, wrapped in classes by RubyMotion). For other Ruby platforms, I created RubyPoint, RubySize and RubyRect (and then also made them available in RubyMotion just because).

The basic classes are:

• RubyDim2d
• RubyPoint < RubyDim2d
• RubySize < RubyDim2d
• RubyRect, composed of a RubyPoint and a RubySize

and for RubyMotion, the same methods are added to the built-in classes:

• CGPoint (or ATSPoint, in osx)
• CGSize
• CGRect (which is composed of a CGPoint and a CGSize)

Dimsome works entirely around the idea of a 'numeric pair', which is basically a 2-member array, each member of which is nil or a Numeric. A 'strict numeric pair' doesn't contain any nils. A 'numeric pairable' is any object that has a to_ary method that returns a numeric pair (eg all Dimsome classes except Rect/CGRect) or is a Numeric (indicating the value for each member, so 3 becomes [3, 3]).

See API Cheatsheet for a list of available methods. Some examples of the most useful bits follow below.

See Testing for how to run the spec/ files, and about Porkbelly, the testing module for use in DragonRuby-GTK.

Initializers and Inspectors

All the Dimsome classes have a make class method and an inspect instance method:

dim2d = Dimsome::RubyDim2d.make(10, 15)
=> Dimsome::RubyDim2d(10, 15)
point = Dimsome::RubyPoint.make(20, 30)
=> Dimsome::RubyPoint(20, 30)
size = Dimsome::RubySize.make(120, 80)
=> Dimsome::RubySize(120, 80)
# RubyRect.make has a number of forms. These are all equivalent:
rect = Dimsome::RubyRect.make(20, 30, 120, 80)
rect = Dimsome::RubyRect.make([20, 30], [120, 80])
rect = Dimsome::RubyRect.make([20, 30, 120, 80])
rect = Dimsome::RubyRect.make(Dimsome::RubyPoint.make(20, 30), Dimsome::RubySize.make(120, 80))
=> Dimsome::RubyRect([20, 30], [120, 80]

and for RubyMotion, these as well:

point = CGPoint(20, 30) # ios only
=> #<CGPoint x=20.0 y=30.0>
point = ATSPoint(20, 30) # osx only
=> #<ATSPoint x=20.0 y=30.0>
size = CGSize.make(120, 80)
=> #<CGSize width=120.0 height=80.0>
rect = CGRect.make(20, 30, 120, 80)
rect = CGRect.make([20, 30], [120, 80])
rect = CGRect.make([20, 30, 120, 80])
rect = CGRect.make(CGPoint.make(20, 30), CGSize.make(120, 80))
=> #<CGRect origin=#<ATSPoint x=20.0 y=30.0> size=#<CGSize width=120.0 height=80.0>>

Alternatively, you can use the convenience methods dim2d, dimp, dims and dimr added to Array:

dim2d = [10, 15].dim2d
=> Dimsome::RubyDim2d(10, 15)
point = [20, 30].dimp
=> Dimsome::RubyPoint(20, 30)
size = [120, 80].dims
=> Dimsome::RubySize(120, 80)
rect = [20, 30, 120, 80].dimr
=> Dimsome::RubyRect([20, 30], [120, 80])

And for RubyMotion, cgp, cgs and cgr:

point = [20, 30].cgp
=> #<ATSPoint x=20.0 y=30.0>
size = [120, 80].dims
=> #<CGSize width=120.0 height=80.0>
cgrect = [20.158, 30.875, 120.6666666, 80].cgr
=> #<CGRect origin=#<ATSPoint x=20.158 y=30.875> size=#<CGSize width=120.6666666 height=80.0>>

Each class also an insp instance method, which gives a shorter description, rounding the values to the nearest whole number:

[10, 15].dim2d.insp
=> "RubyDim2d~(10, 15)"
[20, 30].dimp.insp
=> "RubyPoint~(20, 30)"
[120, 80].dims.insp
=> "RubySize~(120, 80)"
[20, 30, 120, 80].dimr.insp
=> "RubyRect~([20, 30], [120, 80]"
[4.56678999, 8.7765442].dimp.insp

And for RubyMotion:

=> "RubyPoint~(5, 9)"
[4.56678999, 8.7765442].cgp.insp
=> "ATSPoint~(5, 9)"
CGRect.make(20.158, 30.875, 120.6666666, 80).insp
=> "CGRect~([20, 31], [121, 80])"

(I'm going to just note the plain Ruby form examples from here on).

Simple Classes Dim2d, Point, Size (not Rect)

There are getter methods for the instance variables x and y (for Point) and width/w and height/h (for Size).

Setting instance variables by using x= and y= (for Point) and width=/w= and height=/h= (for Size) returns the new value.

Passing a value to x and y (for Dim2d, Point) and width/w and height/h (for Size) creates a new object of the same class, sets the value and returns it for chaining:

p = [3, 4].dimp
=> Dimsome::RubyPoint(3, 4)
p.x
=> 3
p.x = 7
=> 7
p
=> Dimsome::RubyPoint(7, 4)
p.x(9)
=> Dimsome::RubyPoint(9, 4)
p
=> Dimsome::RubyPoint(7, 4)

(Note the chaining setters aren't currently implemented for CGPoint, CGSize)

Basic unary operators/methods -, abs, empty?, diagonal, rough_diagonal and angle:

p = [3, 4].dimp
=> Dimsome::RubyPoint(3, 4)
negative_p = -p
=> Dimsome::RubyPoint(-3, -4)
negative_p.abs
=> Dimsome::RubyPoint(3, 4)
p.empty?
=> false
[0, 0].dimp.empty?
=> true
p.diagonal
=> 5.0
p.rough_diagonal
=> 25
p.angle
=> 0.9272952180016122

Basic binary operators/methods +, -, * and / take a single numeric pairable and return a new object of the same class for chaining:

p = [3, 4].dimp
=> Dimsome::RubyPoint(3, 4)
p * 2
=> Dimsome::RubyPoint(6, 8)
p * [2, nil]
=> Dimsome::RubyPoint(6, 4)
p * [2, nil] + 3
=> Dimsome::RubyPoint(9, 7)
(p + 3) * [2, nil]
=> Dimsome::RubyPoint(12, 7)

(Note `p + 3 *