picrate 0.0.2-java → 0.0.3-java

data/docs/_libraries/vector_utils.md

@@ -0,0 +1,126 @@
+---
+layout: post
+title:  "vector_utils<sup>2</sup>"
+keywords: processing, vector, library
+permalink: libraries/vector_utils.html
+---
+We have created a `vector_utils` library that implements a number of vector methods see sample usage:-
+
+### Vec2D examples
+
+```ruby
+#!/usr/bin/env jruby -v -W2
+# frozen_string_literal: true
+require 'picrate'
+class VogelLayout < Processing::App
+
+  load_library :vector_utils
+
+  attr_reader :points
+
+  def settings
+    size 600, 600
+    smooth 4
+  end
+
+  def setup
+    sketch_title 'Vogel Layout'
+    @points = VectorUtil.vogel_layout(number: 200, node_size: 10.0)
+  end
+
+  def draw
+    background 0
+    fill 200, 130, 100
+    translate width / 2, height / 2
+    points.each do |vec|
+      ellipse vec.x, vec.y, 10, 10
+    end
+  end
+end
+
+VogelLayout.new
+```
+
+```ruby
+#!/usr/bin/env jruby -v -W2
+# frozen_string_literal: true
+require 'picrate'
+
+class SpiralLayout < Processing::App
+  load_library :vector_utils
+
+  attr_reader :points
+
+  def settings
+    size 600, 600
+    smooth 4
+  end
+
+  def setup
+    sketch_title 'Spiral Layout'
+    @points = VectorUtil.spiral_layout(
+      number: 300,
+      radius: 200,
+      resolution: 0.3,
+      spacing: 0.01,
+      inc: 1.15
+    )
+  end
+
+  def draw
+    background 0
+    fill 200, 130, 100
+    translate width / 2, height / 2
+    points.each do |vec|
+      ellipse vec.x, vec.y, 10, 10
+    end
+  end
+end
+
+SpiralLayout.new
+```
+
+### Vec3D example
+
+```ruby
+#!/usr/bin/env jruby -v -W2
+# frozen_string_literal: true
+require 'picrate'
+require 'arcball'
+
+class FibonacciLayout < Processing::App
+
+  load_library :vector_utils
+
+  attr_reader :points
+
+  def settings
+    size 600, 600, P3D
+    smooth 4
+  end
+
+  def setup
+    sketch_title 'Fibonacci Layout'
+    Processing::ArcBall.init self
+    @points = VectorUtil.fibonacci_sphere(number: 500, radius: 300.0)
+  end
+
+  def draw
+    background 0
+    fill 200, 130, 100
+    lights
+    directional_light 200, 200, 200, -1, 1, 0
+    points.each do |vec|
+      push_matrix
+      translate vec.x, vec.y, vec.z
+      polar = VectorUtil.cartesian_to_polar(vec: vec)
+      box 10
+      rotate_y vec.y
+      rotate_z vec.z
+      pop_matrix
+    end
+  end
+end
+
+FibonacciLayout.new
+```

data/docs/_magic/java.md

@@ -0,0 +1,30 @@
+---
+layout: post
+title:  "Java"
+keywords: ruby, java, jruby
+permalink: magic/java.html
+---
+Here is some information about java [inner][inner] classes and [reflection][reflection]. Also see how the pre-processing of the [pde][pde] sketches to valid java creates [java inner classes][pde]. This is all magic stuff that gets hidden from the average user.
+
+### Inner Classes ###
+
+_Stolen from http://www.programmerinterview.com/_
+
+What’s so special about inner classes?
+
+So, what exactly is special about inner classes? Well, the main thing that you must remember about inner classes is that an instance of an inner class has access to all of the members of the outer class, even those that are marked “private”. So, when an instance of the inner class is created, there are no issues with having the inner class access the instance variables of the outer class.
+
+### Reflection ###
+
+_Stolen from stack exchange_
+
+* Reflection is much slower than just calling methods by their name, because it has to inspect the metadata in the bytecode instead of just using precompiled addresses and constants.
+* Reflection is also more powerful: you can retrieve the definition of a protected or final member, remove the protection and manipulate it as if it had been declared mutable!
+* Obviously this subverts many of the guarantees the language normally makes for your programs and that can be extremely dangerous.
+And this pretty much explains when you would use it. Ordinarily, don't. If you want to call a method, just call it. If you want to mutate a member, just declare it mutable instead of going behind the compiler's back.
+
+One useful real-world use of reflection is when writing a framework that has to interoperate with user-defined classes, where the framework author doesn't know what the members (or even the classes) will be. Reflection allows them to deal with any class without knowing it in advance. For instance, I don't think it would be possible to write a complex aspect-oriented library without reflection.
+
+[reflection]:https://docs.oracle.com/javase/tutorial/reflect/
+[inner]:https://docs.oracle.com/javase/tutorial/java/javaOO/innerclasses.html
+[pde]:{{site.github.url}}/magic/processing.html

data/docs/_magic/jruby.md

@@ -0,0 +1,105 @@
+---
+layout: post
+title:  "JRuby"
+keywords: ruby, java, jruby
+permalink: magic/jruby.html
+---
+### java interfaces ###
+JRuby classes can mixin Java interfaces as modules in order to implement them.
+
+```ruby
+class SomeFlexibleClass
+  include java.lang.Runnable
+  include java.lang.Comparable
+end
+```
+
+JRuby does a wonderful thing with Ruby’s blocks, where a block can be converted to the appropriate Java interface. It works by converting the block to a Proc, and then decorating it with a proxy object that runs the block for any method called on the interface. Runnable is the prime example here. You should try this yourself, also see using callbacks [hype][hype] library examples for more sophisticated stuff.
+
+```ruby
+button = javax.swing.JButton.new "Press me!"
+button.add_action_listener { |event| event.source.text = "I done been pressed." }
+```
+Read more about [java interface][wip] etc. Otherwise see [wiki][wiki]
+
+### java reflection ###
+
+In vanilla processing, you can [create libraries][library] in java that can access the sketch `pre`, `draw`, `post`, `mouseEvent` and `keyEvent` methods by java reflection, but you must `register` these methods with the `PApplet`. We can also register custom methods (but sadly only those without parameters, which is why we found another way of dealing with `selectInput` see [chooser][chooser], `movieEvent` see [video_event][video_event]).
+
+Here we show you how to `registerMethods` in a ruby class by java reflection in JRuby (requires the `!become_java` method).
+
+```ruby
+#!/usr/bin/env jruby
+require 'picrate'
+require_relative 'register_send'
+
+class ReflectionVoodoo < Processing::App
+  def settings
+    size 300, 200
+    # pixel_density(2) # for HiDpi screens
+    # smooth # see https://processing.org/reference/smooth_.html
+  end
+
+  def setup
+    sketch_title 'Reflection Voodoo'
+    RegisterSend.new self
+    no_loop
+  end
+
+  def draw
+    fill 0, 0, 200
+    ellipse(170, 115, 70, 100)
+  end
+end
+
+ReflectionVoodoo.new
+```
+
+Here is the class that does the reflection (it needs to become java so that self gets recognized as a java object)
+
+```ruby
+require 'jruby/core_ext' # required to add become_java! method
+
+# This class demonstrates how to use 'reflection' methods in ruby-processing
+# NB: the class must become a java object to get registered. This is an
+# advanced feature in vanilla processing, mainly used by libraries.
+class RegisterSend
+  attr_reader :parent
+
+  def initialize(parent)
+    @parent = parent
+    parent.java_send :registerMethod, [java.lang.String, java.lang.Object], :draw, self
+    parent.java_send :registerMethod, [java.lang.String, java.lang.Object], :pre, self
+  end
+
+  def pre
+    puts 'before draw'
+    parent.background(100)
+  end
+
+  def draw
+    puts 'at begin draw...'
+    parent.fill(200, 100)
+    parent.ellipse(150, 100, 200, 60)
+  end
+  # putting become_java! here works OK
+  become_java!
+end
+```
+
+![reflection voodoo]({{ site.github.url }}/assets/reflection_voodoo.png)
+
+__Note__ how the transparent ellipse is placed on top of the solid ellipse, so the reflection element must get drawn after the original sketch element.
+
+## Java Extensions for JRuby ###
+
+JRuby is a 100% Java implementation of the Ruby programming language. It is Ruby for the JVM. So it is quite possible to write your own ruby code in java, you might do this to better integrate jruby with java or to write your own ruby classes (modules etc) in java see [Method Signatures and Annotations in JRuby extensions][signatures] and [jruby-examples][jruby-examples].
+
+[library]:https://github.com/processing/processing/wiki/Library-Basics
+[wip]:http://kares.org/jruby-ji-doc/
+[wiki]:https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby
+[hype]:{{ site.github.url }}/libraries/hype
+[signatures]:https://github.com/jruby/jruby/wiki/Method-Signatures-and-Annotations-in-JRuby-extensions
+[jruby-examples]:https://github.com/jruby/jruby-examples/tree/master/extensions/basic
+[chooser]:{{ site.github.url }}/libraries/chooser
+[video_event]:{{ site.github.url }}/libraries/video_event

data/docs/_magic/processing.md

@@ -0,0 +1,297 @@
+---
+layout: post
+title:  "Processing"
+keywords: pde, java, processing
+permalink: magic/processing.html
+---
+## __pde__ sketches get pre-processed to __java__ ##
+------
+Part of the attraction of processing is that it hides a lot of java boilerplate stuff from the user.  In vanilla processing all sketches get pre-processed to java prior to compilation:-
+
+So sketch_161005a.pde (an auto-named sketch in the processing ide), gets transformed as follows.
+
+```java
+MyClass var;
+
+void setup(){
+  size(200, 200);
+  var = new MyClass(23);
+}
+
+void draw(){
+  background(255, 0, 0);
+  fill(0, 0, 200);
+  ellipse(100, 100, 90, 120);
+
+}
+
+class MyClass{
+  float var;
+  MyClass(float var){
+  this.var = var;
+  }
+}
+```
+
+See the generated java code below, __note__ all those `imports`, the `class wrapper`, and that `MyClass` becomes a java [inner class][inner]. Also __note__ that `size` has moved to settings (_the processing guys decided not make this change from processing-2.0 to processing-3.0 explicit, in propane and propane we do expect size to be in settings_).
+
+```java
+import processing.core.*;
+import processing.data.*;
+import processing.event.*;
+import processing.opengl.*;
+
+import java.util.HashMap;
+import java.util.ArrayList;
+import java.io.File;
+import java.io.BufferedReader;
+import java.io.PrintWriter;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.IOException;
+
+public class sketch_161005a extends PApplet {
+
+MyClass var;
+
+public void setup(){
+
+  var = new MyClass(23);
+}
+
+public void draw(){
+  background(255, 0, 0);
+  fill(0, 0, 200);
+  ellipse(100, 100, 90, 120);
+
+}
+
+class MyClass{
+  float var;
+  MyClass(float var){
+  this.var = var;
+  }
+}
+  public void settings() {  size(200, 200); }
+  static public void main(String[] passedArgs) {
+    String[] appletArgs = new String[] { "sketch_161005a" };
+    if (passedArgs != null) {
+      PApplet.main(concat(appletArgs, passedArgs));
+    } else {
+      PApplet.main(appletArgs);
+    }
+  }
+}
+```
+
+## java reflection gets used a lot in processing ##
+------
+
+It is an unfortunate truth that [java reflection methods][reflection] are popular with both processing developers and some developers of supporting libraries. It is unfortunate because we have to go through hoops to use these methods in propane (and ruby-processing). The `captureEvent` and `videoEvent` are examples of reflection methods from the processing video developers. But we have made these readily available to propane users as a [simple library][library] load `load_library :video_event`. This is what you would do (if we had not created the `video_event` library):-
+
+- create a java class `VideoInterface`
+- compile the java class (including classpath)
+- create a jar (and place it in the same folder as your sketch)
+- modify the sketch to both `require` the `jar` and to `include` the interface.
+
+### VideoInterface.java ###
+
+See [javadoc here][video]
+```java
+package monkstone.videoevent;
+import processing.video.Movie;
+import processing.video.Capture;
+/**
+ * This interface makes it easier/possible to use the reflection methods
+ * from Movie and Capture classes in Processing::App in propane
+ * @author Martin Prout
+ */
+public interface VideoInterface {
+    /**
+     * Used to implement reflection method in PApplet
+     * @see processing.video.Movie
+     * @param movie Movie
+     */
+    public void movieEvent(Movie movie);
+    /**
+     * Used to implement reflection method in PApplet
+     * @see processing.video.Capture
+     * @param capture Capture
+     */
+    public void captureEvent(Capture capture);    
+}
+```
+
+To match packaging the java file needs to be nested in `monkstone/videoevent` folders (it is unwise not to have a package) and compile and jar as follows, requires jdk8+.
+
+```bash
+# NB: classpath needs to be a fully qualified path to jars (not as below)
+javac -cp video.jar:core.jar monkstone/videoevent/VideoInterface.java
+
+jar -cvf video_event.jar monkstone
+```
+
+See below a sketch which using this VideoEvent interface, see the version using the propane provided `:video_event` library [here][bw]
+
+### black_white_capture.rb ###
+
+```ruby
+require 'picrate'
+require_relative 'video_event'
+
+class BlackAndWhiteCapture < Processing::App
+  load_libraries :video
+  include_package 'processing.video'
+
+  include Java::MonkstoneVideoevent::VideoInterface
+
+  attr_reader :cam, :my_shader
+
+  def setup
+    sketch_title 'Black & White Capture'
+    @my_shader = load_shader('bwfrag.glsl')
+    start_capture(width, height)
+  end
+
+  def start_capture(w, h)
+    @cam = Capture.new(self, w, h)
+    cam.start
+  end
+
+  def draw
+    image(cam, 0, 0)
+    return if mouse_pressed?
+    filter(my_shader)
+  end
+
+  # using snake case to match java reflection method
+  def captureEvent(c)
+    c.read
+  end
+
+  def settings
+    size(960, 544, P2D)
+  end
+end
+
+BlackAndWhiteCapture.new
+```
+
+Now where this knowledge becomes really useful, is when you want to use another library, say the vanilla processing carnivore library whose `packetEvent` method also depends on java relection. Here is a suitable CarnivoreListener class.
+
+### CarnivoreListener.java ###
+
+```java
+package monkstone;
+
+/*
+* Best to use a package to avoid namespace clashes, create your own
+*/
+public interface CarnivoreListener {
+  /*
+  * @param packet the CarnivorePacket, a reflection method
+  */
+  public void packetEvent(org.rsg.carnivore.CarnivorePacket packet);  
+}
+```
+
+Which we compile as before
+
+```bash
+# NB: classpath needs to be a fully qualified path to jar (not as below)
+javac -cp carnivore.jar monkstone/CarnivoreListener.java
+
+jar -cvf carnivore_listener.jar monkstone
+```
+
+Here is an example sketch:-
+
+### carnivore1.rb ###
+
+```ruby
+# A Simple Carnivore Client -- print packets in Processing console
+#
+# Note: requires Carnivore Library for Processing (https://r-s-g.org/carnivore)
+#
+# + Windows:  first install winpcap (https://winpcap.org)
+# + Mac:      first open a Terminal and execute this commmand: sudo chmod 777 /dev/bpf*
+#             you need to do this each time you reboot Mac
+# + Linux:    run with difficulty (run with sudo rights arghh!!!) also install libpcap
+require 'picrate'
+
+class CarnivoreListener < Processing::App
+  load_library :carnivore
+  include_package 'org.rsg.carnivore'
+  java_import 'org.rsg.lib.Log'
+  require_relative 'carnivore_listener'
+  include Java::Monkstone::CarnivoreListener
+
+  attr_reader :c
+
+  def settings
+    size(600, 400)
+  end
+
+  def setup
+    sketch_title 'Carnivore Example'
+    background(255)  
+    @c = CarnivoreP5.new(self)
+    Log.setDebug(true) # comment out for quiet mode
+    # c.setVolumeLimit(4) #limit the output volume (optional)
+    # c.setShouldSkipUDP(true) #tcp packets only (optional)
+  end
+
+  def draw
+  end
+
+  # Called each time a new packet arrives
+  def packetEvent(p)
+    puts(format('(%s packet) %s > %s', p.strTransportProtocol, p.senderSocket, p.receiverSocket))
+    # puts(format('Payload: %s', p.ascii))
+    # puts("---------------------------\n")
+  end
+end
+
+CarnivoreListener.new
+```
+
+
+Another example of reflection usage the vanilla processing `selectInput` utility, that enable use of the native file chooser:-
+
+### Native File Chooser ###
+
+What a native file chooser sketch looks like in java, the `selectInput` [callback][callback] relies on java reflection under the hood. We have to explicity provide such a signature to use this feature in propane hence [FileChooser][FileChooser] library.
+
+```java
+public class chooser extends PApplet {
+
+public void setup() {
+  selectInput("Select a file to process:", "fileSelected");
+}
+
+public void fileSelected(File selection) {
+  if (selection == null) {
+    println("Window was closed or the user hit cancel.");
+  } else {
+    println("User selected " + selection.getAbsolutePath());
+  }
+}
+  static public void main(String[] passedArgs) {
+    String[] appletArgs = new String[] { "chooser" };
+    if (passedArgs != null) {
+      PApplet.main(concat(appletArgs, passedArgs));
+    } else {
+      PApplet.main(appletArgs);
+    }
+  }
+}
+```
+
+Read more about java [reflection here][reflection].
+
+[inner]:https://docs.oracle.com/javase/tutorial/java/javaOO/innerclasses.html
+[FileChooser]:{{ site.github.url }}/classes/chooser
+[callback]:https://processing.org/reference/selectInput_.html
+[library]:{{ site.github.url }}/libraries/video_event.html
+[reflection]:https://docs.oracle.com/javase/tutorial/reflect/
+[bw]:https://github.com/ruby-processing/picrate-examples/blob/master/library/video/capture/black_white_capture.rb

data/docs/_magic/ruby.md

@@ -0,0 +1,31 @@
+---
+layout: post
+title:  "Ruby"
+keywords: ruby, java, meta
+permalink: magic/custom.html
+---
+Here will go stuff about [meta programming][meta] etc, which is how we bring you Processing::Proxy etc see `app.rb`.
+
+Using a Proxy module we are able create `java inner class` type access to including classes (_like vanilla processing_), we do this by creating custom method `:method_missing` and `:respond_to_missing?` methods
+
+```ruby
+
+# @HACK purists may prefer 'forwardable' to the use of Proxy
+# Importing PConstants here to access the processing constants
+module Proxy
+  include Math
+  include HelperMethods
+  include Java::ProcessingCore::PConstants
+
+  def respond_to_missing?(symbol, include_private = false)
+    Propane.app.respond_to?(symbol, include_private) || super
+  end
+
+  def method_missing(name, *args, &block)
+    return Propane.app.send(name, *args) if Propane.app.respond_to? name
+    super
+  end
+end # Processing::Proxy
+```
+
+[meta]:https://www.toptal.com/ruby/ruby-metaprogramming-cooler-than-it-sounds

data/docs/_methods/alternative_methods.md

@@ -0,0 +1,66 @@
+---
+layout: post
+title:  "alternative ruby methods"
+permalink: methods/alternative_methods.html
+---
+<style>
+table{
+    border-collapse: collapse;
+    border-spacing: 0;
+    border:2px solid #0000FF;
+}
+
+th{
+    border:2px solid #0000FF;
+}
+</style>
+You can use most [processing methods][processing] in propane, but where possible you should prefer these ruby alternatives (you should also prefer Vec2D and Vec3D to PVector).
+Here is a list of ruby alternatives to some 'processing' convenience methods; which with the exception of `color`, `map1d`, `p5map`, `degrees` and `radians` are just regular ruby methods.
+
+|function       |processing            |propane           |
+|----------     |-------------       |------               |
+|camera         |`camera(args)`      |`kamera(hash_args)`  |
+|color string   |`color(#cc6600)`      |`color('#cc6600')` |
+|date/time      |                      |`t = Time.now`       |
+|               |`day`                   |`t.day`              |
+|               |`hour`                  |`t.hour`             |
+|               |`minute`                |`t.minute`           |
+|               |`second`                |`t.second`           |
+|               |`year`                  |`t.year`             |
+|custom math    |`map(x, b0, eo, b1, e1)`|`map1d(x, (b0..e0), (b1..e1))`|
+|               |`map(x, b0, eo, b1, e1)`|`p5map(x, b0, e0, b1, e1)`|
+|               |`max(array)            `|`array.max`        |
+|               |`min(array)            `|`array.min`        |
+|conversion     |`degrees(theta)`        |`theta.degrees`    |
+|conversion     |`radians(theta)`        |`theta.radians`    |
+|conversion     |`hex(string)`           |`string.hex`       |
+|conversion     |`unhex(string)`         |`string.to_i(base=16)`|
+|conversion     |`binary(c)`             |`c.to_s(2)`        |
+|conversion     |`unbinary(string)`      |`string.to_i(base=2)`|
+|math           |`abs(x)`                |`x.abs`            |
+|math           |`round(x)`              |`x.round`          |
+|math           |`ceil(x)`               |`x.ceil`           |
+|math           |`random(x)`             |`rand(x)`          |
+|math           |`random(a, b)`          |`rand(a..b)`       |
+|math power     |`pow(a, b)`             |`a**b`             |
+|square         |`sq(x)`                 |`x * x`            |
+|print          |`println(x)`            |`puts x`           |
+|format         |`trim(string)`          |`string.strip`     |
+|format         |`nf(float_value, 0, 2)` |`format('%.2f', float_value)`|
+|format         |`nf(num, digit)`        |`num.to_s.rjust(digit, '0')`|
+|format         |`nf(nf(num, left, right)`|`see below`     |
+
+`num.to_s.rjust(left, '0').ljust(left + right, '0')`
+
+For examples of using time in sketches see [learning JRubyArt blog][time], [timestamp][timestamp] and this [clock sketch][clock].
+
+For example of `kamera` usage see [kamera][kamera]. To use `selectInput` see link to `File Chooser` in page header. We actually use the ruby Enumerable methods `max` and `min` methods to make `max(*array)` and `min(*methods)` available in propane, so you could use the processing form providing you splat the array, but it is simpler to use the ruby method directly further you have the option with ruby of changing the [comparator via a block][comparator].
+
+NB: if you have any trouble with `save` or `save_frame` then use the option of providing an absolute path.  You can easily do this using the `data_path` wrapper that does it for you see [data_path method][data_path].
+
+[data_path]:{{site.github.url}}/data_path/
+[time]:https://monkstone.github.io/time
+[timestamp]:https://monkstone.github.io/timestamp/
+[clock]:https://github.com/ruby-processing/picrate-examples/blob/master//library/fastmath/clock.rb
+[kamera]:https://github.com/ruby-processing/picrate-examples/blob/master//basics/camera/kmove_eye.rb
+[processing]:https://processing.org/reference/