picrate 0.0.2-java → 0.0.3-java

data/docs/_libraries/gems.md

@@ -0,0 +1,57 @@
+---
+layout: post
+title:  "gems<sup>4</sup>"
+keywords: library, gem
+permalink: libraries/gems.html
+---
+The most convenient library to use in `ruby` is a `gem`, and `picrate` is no different, however in addition to pure `ruby gems` there are a number of `gems` that are wrappers for `java` libraries that can be used in `picrate`:-
+
+#### ArcBall gem
+
+This library is installed as a `picrate` dependency, and is used in 3D sketches to provide arcball manipulation of a 3D object (using quaternions in java).
+
+```ruby
+require 'arcball'
+
+class MySketch
+  ...
+  def setup
+    ...
+    Processing::ArcBall.init(self)
+    ...
+
+```
+
+In the above snippet the sketch viewport is centered at half width and half height of the sketch, which is also the center of rotation. Manipulate the object in the sketch center by dragging the mouse in direction of rotation, or us the mousewheel to zoom.
+
+#### Toxiclibs gem
+
+Is a ruby wrapper around Karsten Schmidts (aka toxi / postspectacular) toxiclibs libraries, in `picrate` you should prefer to use this collection of libraries as a `gem`. The toxiclibs libraries are a set of building blocks for computational design, that were  designed to be compatible with processing-2.2.1 (and earlier versions of java). The [gem][toxi] is maintained independently from the version available in the processing ide, and the java code has been updated to make use java-8 and to be compatible with `processing-3.3.7` and hence `picrate`. The gem also provides a convenient [namespaces][ntoxi] for the toxiclibs libraries see [examples sketches][texamples], so you don't have to individualy import the java classes/packages.
+
+#### Geomerative gem
+
+Is a ruby wrapper around Ricard Marxer (@rikrd @ricardmp) [geomerative library][geomerative]. It extends 2D geometry operations to facilitate generative geometry. Includes a TrueType font and an SVG interpreters. See the [gem here][geomgem], which has been updated for java-8 and under the hood imports for Geomerative classes, so that you don't have to.
+
+#### PBox2D gem
+
+Is a java and ruby wrapper around Daniel Murphy (@dmurph) JBox2D library (_JBox2D is a close Java port of Erin Catto's excellent C++ Box2D physics engine and Google's LiquidFun physics Engine._). The java wrapper provides an interface between the processing and game physics worlds.
+
+#### Wordcram gem
+
+Is a ruby wrapper around the [Wordcram library][wordcram] by Dan Bernier, that can be used to create world clouds in JRubyArt or picrate. See [documentation][docu].
+
+### Raytracing gem
+
+The [joonsrenderer gem][joons] can be used to ray trace 3D objects in processing sketches. Includes an updated to java-8 version of the java [sunflow library][sunflow], and uses a more up to date version of the [janino compiler][janino].
+
+
+[janino]:http://janino-compiler.github.io/janino/
+[sunflow]:http://sunflow.sourceforge.net/
+[joons]:https://ruby-processing.github.io/joonsrenderer/
+[docu]:https://ruby-processing.github.io/
+[wordcram]:http://wordcram.org/
+[geomgem]:https://ruby-processing.github.io/geomerativegem/
+[geomerative]:https://github.com/rikrd/geomerative
+[ntoxi]:http://ruby-processing.github.io/toxicgem/namespace/
+[toxi]:http://ruby-processing.github.io/toxicgem/toxiclibs/update/2015/11/28/introduction.html
+[texamples]:https://github.com/ruby-processing/picrate-examples/tree/master/external_library/gem/toxiclibs

data/docs/_libraries/library_proxy.md

@@ -0,0 +1,9 @@
+---
+layout: post
+title:  "library_proxy<sup>2</sup>"
+keywords: processing, abstract class, library
+permalink: libraries/library_proxy.html
+---
+For advanced users only, we have created a `library_proxy` library that give access to vanilla processing [library methods][library] for more details see classes section.
+
+[library]:https://github.com/processing/processing/wiki/Library-Basics

data/docs/_libraries/picrate.md

@@ -0,0 +1,511 @@
+---
+layout: post
+title:  "picrate<sup>1, 2</sup>"
+keywords: library, boids, control_panel
+permalink: libraries/picrate.html
+---
+Propane provides a number of libraries that you can use _out of the box_, but which still need to be loaded to use them in you sketches see examples below:-
+
+
+### Boids library ###
+<sup>1</sup><i>A built in pure ruby library</i>
+
+The [original boids library][original] was created by Jeremy Ashkenas to demonstrate a pure 'ruby' library for ruby processing, this updated version has the same goal. However it is updated to make use of [Vec3D][vec3d] and [Vec2D][vec2d] classes (picrate features) and keyword arguments (ruby-2.1). It also use [forwardable][forwardable]. To see usage of now correctly implemented `angle` (heading) see [simple example][example].
+
+See the full library code below:-
+
+```ruby
+# frozen_string_literal: true
+# Boids -- after Tom de Smedt.
+# See his Python version: http://nodebox.net/code/index.php/Boids
+# This is an example of how a pure-Ruby library can work. Original for
+# ruby-processing Jeremy Ashkenas. Reworked, re-factored for picrate
+# by Martin Prout, features forwardable, keyword args, Vec3D and Vec2D.
+class Boid
+  attr_reader :boids
+  attr_accessor :vel, :pos, :is_perching, :perch_time
+  def initialize(boids, pos)
+    @boids, @flock = boids, boids
+    @pos = pos
+    @vel = Vec3D.new
+    @is_perching = false
+    @perch_time = 0.0
+  end
+
+  def cohesion(d:)
+    # Boids gravitate towards the center of the flock,
+    # Which is the averaged position of the rest of the boids.
+    vect = Vec3D.new
+    @boids.each do |boid|
+      vect += boid.pos unless boid == self
+    end
+    count = @boids.length - 1.0
+    vect /= count
+    (vect - pos) / d
+  end
+
+  def separation(radius:)
+    # Boids don't like to cuddle.
+    vect = Vec3D.new
+    @boids.each do |boid|
+      if boid != self
+        dv = pos - boid.pos
+        vect += dv if dv.mag < radius
+      end
+    end
+    vect
+  end
+
+  def alignment(d:)
+    # Boids like to fly at the speed of traffic.
+    vect = Vec3D.new
+    @boids.each do |boid|
+      vect += boid.vel if boid != self
+    end
+    count = @boids.length - 1.0
+    vect /= count
+    (vect - vel) / d
+  end
+
+  def limit(max:)
+    # Tweet, Tweet! The boid police will bust you for breaking the speed limit.
+    most = [vel.x.abs, vel.y.abs, vel.z.abs].max
+    return if most < max
+    scale = max / most.to_f
+    @vel *= scale
+  end
+
+  def angle
+    Vec2D.new(vel.x, vel.y).heading
+  end
+
+  def goal(target, d = 50.0)
+    # Them boids is hungry.
+    (target - pos) / d
+  end
+end
+
+require 'forwardable'
+
+# The Boids class
+class Boids
+  include Enumerable
+  extend Forwardable
+  def_delegators(:@boids, :reject, :<<, :each, :shuffle!, :length, :next)
+
+  attr_reader :has_goal, :perch, :perch_tm, :perch_y
+
+  def initialize
+    @boids = []
+  end
+
+  def self.flock(n:, x:, y:, w:, h:)
+    flock = Boids.new.setup(n, x, y, w, h)
+    flock.reset_goal(Vec3D.new(w / 2, h / 2, 0))
+  end
+
+  def setup(n, x, y, w, h)
+    n.times do
+      dx, dy = rand(w), rand(h)
+      z = rand(200.0)
+      self << Boid.new(self, Vec3D.new(x + dx, y + dy, z))
+    end
+    @x, @y, @w, @h = x, y, w, h
+    @scattered = false
+    @scatter = 0.005
+    @scatter_time = 50.0
+    @scatter_i = 0.0
+    @perch = 1.0 # Lower this number to divebomb.
+    @perch_y = h
+    @perch_tm = -> { 25.0 + rand(50.0) }
+    @has_goal = false
+    @flee = false
+    @goal = Vec3D.new
+    self
+  end
+
+  def scatter(chance = 0.005, frames = 50.0)
+    @scatter = chance
+    @scatter_time = frames
+  end
+
+  def no_scatter
+    @scatter = 0.0
+  end
+
+  def perch(ground = nil, chance = 1.0, frames = nil)
+    @perch_tm = frames.nil? ? -> { 25.0 + rand(50.0) } : frames
+    @perch_y = ground.nil? ? @h : ground
+    @perch = chance
+  end
+
+  def no_perch
+    @perch = 0.0
+  end
+
+  def reset_goal(target)
+    @has_goal = true
+    @flee = false
+    @goal = target
+    self
+  end
+
+  def goal(target:, flee:)
+    @has_goal = true
+    @flee = flee
+    @goal = target
+    self
+  end
+
+  def no_goal
+    @has_goal = false
+  end
+
+  def constrain
+    # Put them boids in a cage.
+    dx, dy = @w * 0.1, @h * 0.1
+    each do |b|
+      b.vel.x += rand(dx) if b.pos.x < @x - dx
+      b.vel.y += rand(dy) if b.pos.y < @y - dy
+      b.vel.x -= rand(dx) if b.pos.x > @x + @w + dx
+      b.vel.y -= rand(dy) if b.pos.y > @y + @h + dy
+      b.vel.z += 10.0 if b.pos.z < 0.0
+      b.vel.z -= 10.0 if b.pos.z > 100.0
+      next unless b.pos.y > perch_y && rand < perch
+      b.pos.y = perch_y
+      b.vel.y = b.vel.y.abs * -0.2
+      b.is_perching = true
+      b.perch_time = perch_tm.respond_to?(:call) ? perch_tm.call : perch_tm
+    end
+  end
+
+  def update(goal: 20.0, limit: 30.0, **args)
+    shuffled = args.fetch(:shuffled, true)
+    cohesion = args.fetch(:cohesion, 100)
+    separation = args.fetch(:separation, 10)
+    alignment = args.fetch(:alignment, 5.0)
+    # Just flutter, little boids ... just flutter away.
+    # Shuffling keeps things flowing smooth.
+    shuffle! if shuffled
+    m1 = 1.0 # cohesion
+    m2 = 1.0 # separation
+    m3 = 1.0 # alignment
+    m4 = 1.0 # goal
+    @scattered = true if !@scattered && rand < @scatter
+    if @scattered
+      m1 = -m1
+      m3 *= 0.25
+      @scatter_i += 1.0
+    end
+    if @scatter_i >= @scatter_time
+      @scattered = false
+      @scatter_i = 0.0
+    end
+    m4 = 0.0 unless has_goal
+    m4 = -m4 if @flee
+    each do |b|
+      if b.is_perching
+        if b.perch_time > 0.0
+          b.perch_time -= 1.0
+          next
+        else
+          b.is_perching = false
+        end
+      end
+      v1 = b.cohesion(d: cohesion)
+      v2 = b.separation(radius: separation)
+      v3 = b.alignment(d: alignment)
+      v4 = b.goal(@goal, goal)
+      # NB: vector must precede scalar in '*' operation below
+      b.vel += (v1 * m1 + v2 * m2 + v3 * m3 + v4 * m4)
+      b.limit(max: limit)
+      b.pos += b.vel
+    end
+    constrain
+  end
+end
+
+```
+
+Here is the re-factored Flight Patterns Sketch:-
+```ruby
+#!/usr/bin/env jruby -v -w
+# Description:
+# Flight Patterns is that ol' Euruko 2008 demo.
+# Reworked version for Propane
+# Usage:
+# Drag mouse to steer 'invisible' flock attractor, use 'f' key to toggle flee
+# Mouse 'click' to toggle 'sphere' or 'circle' display
+require 'picrate'
+
+class FlightPatterns < Processing::App
+  load_library :boids
+
+  attr_reader :flee, :radius
+
+  def settings
+    size 1024, 768, P3D
+  end
+
+  def setup
+    sketch_title 'Flight Patterns'    
+    sphere_detail 8
+    color_mode RGB, 1.0
+    no_stroke
+    shininess 1.0
+    specular 0.3, 0.1, 0.1
+    emissive 0.03, 0.03, 0.1
+    @radius = 0.02 * height
+    @click = false
+    @flee = false
+    @flocks = (0..3).map { Boids.flock(n: 20, x: 0, y: 0, w: width, h: height) }
+  end
+
+  def mouse_pressed
+    @click = !@click
+  end
+
+  def key_pressed
+    return unless key == 'f'
+    @flee = !@flee
+  end
+
+  def draw
+    background 0.05
+    ambient_light 0.01, 0.01, 0.01
+    light_specular 0.4, 0.2, 0.2
+    point_light 1.0, 1.0, 1.0, mouse_x, mouse_y, 190
+    @flocks.each_with_index do |flock, i|
+      flock.goal(target: Vec3D.new(mouse_x, mouse_y, 0), flee: @flee)
+      flock.update(goal: 185, limit: 13.5)
+      flock.each do |boid|
+        r = (0.15 * boid.pos.z) + radius
+        case i
+        when 0 then fill 0.85, 0.65, 0.65
+        when 1 then fill 0.65, 0.85, 0.65
+        when 2 then fill 0.65, 0.65, 0.85
+        end
+        push_matrix
+        point_array = (boid.pos.to_a).map { |p| p - (r / 2.0) }
+        translate(*point_array)
+        @click ? sphere(r / 2) : ellipse(0, 0, r, r)
+        @click ? hint(ENABLE_DEPTH_TEST) : hint(DISABLE_DEPTH_TEST)
+        pop_matrix
+      end
+    end
+  end
+end
+
+FlightPatterns.new
+
+```
+
+
+### Control Panel library
+
+<sup>2</sup><i>A built in hybrid ruby/java library</i>
+
+Start by loading in the control_panel library, and then define your panel in setup like so:
+
+```ruby
+#!/usr/bin/env jruby -v -W2
+# frozen_string_literal: true
+require 'picrate'
+# Iconic ruby-processing example for Propane
+class JWishy < Processing::App
+  load_library :control_panel
+
+  attr_reader :alpha, :back_color, :bluish, :hide, :magnitude, :panel
+  attr_reader :x_wiggle, :y_wiggle, :go_big, :shape
+
+  def settings
+    size 600, 600  
+  end
+
+  def setup
+    sketch_title 'Wishy Worm'
+    control_panel do |c|
+      c.title 'Control Panel'
+      c.look_feel 'Nimbus'
+      c.slider :bluish, 0.0..1.0, 0.5
+      c.slider :alpha,  0.0..1.0, 0.5
+      c.checkbox :go_big, false
+      c.button :reset
+      c.menu :shape, %w[oval square triangle], 'oval'
+      @panel = c
+    end
+    @hide = false
+    @x_wiggle, @y_wiggle = 10.0, 0
+    @magnitude = 8.15
+    @back_color = [0.06, 0.03, 0.18]
+    color_mode RGB, 1
+    ellipse_mode CORNER
+    smooth
+  end
+
+#....rest of code
+
+
+  def draw
+    # only make control_panel visible once, or again when hide is false
+    unless hide
+      @hide = true
+      panel.set_visible(hide)
+    end
+#.... rest of draw   
+
+JWishy.new
+
+
+```
+![JWishy]({{site.github.url}}/assets/jwishy.png)
+
+See also [penrose](https://github.com/ruby-processing/picrate-examples/blob/master/library/vecmath/vec2d/penrose.rb) and [bezier playground](https://github.com/ruby-processing/picrate-examples/blob/master/contributed/bezier_playground.rb) sketches. See ruby code [here](https://github.com/ruby-processing/picrate/blob/master/library/control_panel/control_panel.rb).
+
+### Video Event Library ###
+
+<sup>2</sup><i>A built in hybrid ruby/java library</i>
+The video library should be installed using `picrate --install video`
+
+The purpose of the `video_event` library is to allow you to use the vanilla processing reflection methods `captureEvent` and `movieEvent` from the processing `video` library. _It is almost impossible to use vanilla processing reflection methods without this sort of wrapper_.
+
+If MacOS users experience difficulty with the video library they should probably rename the binary folder from `macosx64` to `macosx`.  However it seems as though the binaries get dynamically loaded from the video library, and this may not be necessary see [Line 178][178] (personal communication Gottfreid Haider) but this is pure conjecture in case of picrate.
+
+A movie example:-
+
+```ruby
+#!/usr/bin/env jruby -w
+require 'picrate'
+# Loop.
+#
+# Shows how to load and play a QuickTime movie file.
+class Loop < Processing::App
+  load_libraries :video, :video_event
+  include_package 'processing.video'
+
+  attr_reader :movie
+
+  def setup
+    sketch_title 'Loop'
+    background(0)
+    # Load and play the video in a loop
+    @movie = Movie.new(self, data_path('transit.mov'))
+    movie.loop
+  end
+
+  def draw
+    image(movie, 0, 0, width, height)
+  end
+
+  # use camel case to match java reflect method
+  def movieEvent(m)
+    m.read
+  end
+
+  def settings
+    size 640, 360
+  end
+end
+
+Loop.new
+```
+
+A capture example-
+
+```ruby
+#!/usr/bin/env jruby -w
+require 'picrate'
+class TestCapture < Processing::App
+  load_libraries :video, :video_event
+
+  include_package 'processing.video'
+
+  attr_reader :cam
+
+  def setup
+    sketch_title 'Test Capture'
+    cameras = Capture.list
+    fail 'There are no cameras available for capture.' if (cameras.length == 0)
+    p 'Matching cameras available:'
+    size_pattern = Regexp.new(format('%dx%d', width, height))
+    select = cameras.grep size_pattern # filter available cameras
+    select.uniq.map { |cam| p cam.strip }
+    fail 'There are no matching cameras.' if (select.length == 0)
+    start_capture(select[0])
+  end
+
+  def start_capture(cam_string)
+    # The camera can be initialized directly using an
+    # element from the array returned by list:
+    @cam = Capture.new(self, cam_string)
+    p format('Using camera %s', cam_string)
+    cam.start
+  end
+
+  def draw
+    image(cam, 0, 0, width, height)
+    # The following does the same, and is faster when just drawing the image
+    # without any additional resizing, transformations, or tint.
+    # set(0, 0, cam)
+  end
+
+  def captureEvent(c)
+    c.read
+  end
+
+  def settings
+    size 1280, 720, P2D
+  end
+end
+
+TestCapture.new
+```
+
+### File Chooser Library ###
+
+<sup>2</sup><i>A built in hybrid ruby/java library</i>
+
+Start by loading in the chooser library, the purpose of this library is to allow you to use the vanilla processing interface to the `native file chooser` (it is almost impossible to use vanilla processing reflection methods without this sort of wrapper)
+
+```ruby
+#!/usr/bin/env jruby -v -W2
+
+require 'picrate'
+###########
+# Example Native File Chooser using vanilla processing
+# select_input, and file_selected
+###########
+class SelectFile < Processing::App
+
+  load_library :file_chooser
+
+
+  def settings
+    size 200, 100
+  end
+
+  def setup
+    sketch_title 'Select File, native chooser'
+    # java_signature 'void selectInput(String, String)'
+    select_input('Select a File', 'file_selected')
+  end
+
+  #  signature 'void file_selected(java.io.File file)'
+  def file_selected(file)
+    puts file.get_absolute_path unless file.nil?
+  end
+end
+
+SelectFile.new
+```
+
+See also [these examples](https://github.com/ruby-processing/picrate-examples/tree/master/processing_app/library/file_chooser)
+
+[178]:https://github.com/processing/processing-video/blob/master/src/processing/video/Video.java
+
+
+[original]:https://github.com/jashkenas/ruby-processing/blob/8865c934318e05e62cbfa2603e661275b1cffd31/library/boids/boids.rb
+[vec3d]:https://ruby-processing.github.io/classes/vec3d/
+[vec2d]:https://ruby-processing.github.io/classes/vec2d/
+[forwardable]:https://ruby-doc.org/stdlib-2.0.0/libdoc/forwardable/rdoc/Forwardable.html
+[example]:https://github.com/ruby-processing/picrate-examples/blob/master/library/boids/boids_example.rb

data/docs/_libraries/processing.md

@@ -0,0 +1,126 @@
+---
+layout: post
+title:  "processing<sup>5</sup>"
+keywords: library, boids, control_panel
+permalink: libraries/processing.html
+---
+### Sound library ###
+
+<sup>5</sup><i>A vanilla processing (java) library</i>
+
+First load the sound library (assumes it was installed using `picrate --install Sound`)
+
+You might just as well `include_package` to get namespace access to the `processing.sound` package.
+
+Note processing currently supports only 32 bit drivers on raspberrypi, and we assume 64 bit on regular linux.
+
+```ruby
+# This is a simple pink noise generator. It can be started with .play(amp).
+# In this example it is started and stopped by clicking into the renderer window.
+require 'picrate'
+
+class PinkNoiseApp < Processing::App
+  load_library :sound
+  include_package 'processing.sound'
+
+  attr_reader :amp, :noise
+
+  def settings
+    size(640, 360)
+  end
+
+  def setup
+    sketch_title 'Pink Noise'
+    background(255)
+    @amp = 0.0
+    # Create the noise generator
+    @noise = PinkNoise.new(self)
+    noise.play(amp)
+  end      
+
+  def draw
+    # Map mouseX from 0.0 to 1.0 for amplitude
+    noise.amp(map1d(mouse_x, (0..width), (0.0..1.0)))
+    # Map mouseY from -1.0 to 1.0 for left to right
+    noise.pan(map1d(mouse_y, (0..height), (-1.0..1.0)))
+  end
+end
+
+PinkNoiseApp.new
+```
+
+### Listing vanilla processing contributed libraries and their urls ###
+
+```bash
+wget http://download.processing.org/contribs/contribs.txt
+```
+
+### Installing contributed vanilla processing libraries ###
+
+Install libraries to your `~/.picrate/libraries` folder.  NB: this created for you when you install the `glvideo` or `sound` libraries. The one unfortunate / fortunate thing is that you will be responsible for updating versions manually (can be good / bad thing).
+
+```bash
+picrate -i Sound
+picrate -i Video
+picrate -i glvideo
+```
+
+It can make sense to convert the library names and jars from `camelcase` to `snakecase`, (_ie when library creators have messed up_) but just be to be consistent, as example below
+
+```bash
+cd ~/.picrate/libraries
+wget http://staff.city.ac.uk/~jwo/giCentre/utils/gicentreUtils.zip
+unzip gicentreUtils.zip # NB: British English spelling of centre
+mv gicentreUtils gicenter_utils # Use snake case, and convert spelling
+cd gicenter_utils/library
+mv gicentreUtils.jar gicenter_utils.jar
+```
+Here is an example sketch translated to picrate, main differences are how we load libraries and access package namespace in picrate. Also note the use of the data_path wrapper to access sketch data folder. Another twist is the need to cast array of ruby Numbers to java float.
+
+```ruby
+require 'picrate'
+# Sketch to demonstrate the use of the BarChart class to draw simple bar charts.
+# Version 1.3, 6th February, 2016.
+# Author Jo Wood, giCentre.
+class BarChartSketch < Processing::App
+  load_library :gicenter_utils
+  include_package 'org.gicentre.utils.stat' # British spelling
+
+  def settings
+    size(800, 300)
+    smooth
+  end
+
+  def setup # a static sketch no need for draw loop
+    sketch_title 'Bar Chart Sketch'
+    title_font = load_font(data_path('Helvetica-22.vlw'))
+    small_font = load_font(data_path('Helvetica-12.vlw'))
+    text_font(small_font)
+    bar_chart = BarChart.new(self)
+    data_float = [
+      2_462, 2_801, 3_280, 3_983, 4_490, 4_894, 5_642, 6_322, 6_489, 6_401,
+      7_657, 9_649, 9_767, 12_167, 15_154, 18_200, 23_124, 28_645, 39_471
+    ]
+    bar_chart.setData(data_float.to_java(:float))
+    data_label = %w(1830 1840 1850 1860 1870 1880 1890 1900 1910 1920 1930 1940 1950 1960 1970 1980 1990 2000 2010)
+    bar_chart.setBarLabels(data_label)
+    bar_chart.setBarColour(color(200, 80, 80, 100))
+    bar_chart.setBarGap(2)
+    bar_chart.setValueFormat('$###,###')
+    bar_chart.showValueAxis(true)
+    bar_chart.showCategoryAxis(true)
+    background(255)
+    bar_chart.draw(10, 10, width - 20, height - 20)
+    fill(120)
+    text_font(title_font)
+    text('Income per person, United Kingdom', 70, 30)
+    text_height = text_ascent # of title font
+    text_font(small_font)
+    text('Gross domestic product measured in inflation-corrected $US', 70, 30 + text_height)
+  end
+end
+
+BarChartSketch.new
+```
+
+![bar chart sketch]({{ site.github.url }}/assets/bar_chart.png)