ruby-gr 0.0.15 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d9ef46d38e4a4cb1d52b933af0b1d3a44de17e780bbb0dc404ac62a40026827
-  data.tar.gz: 9084d96ecd560a87d7540d736e87312cc3351f85bcdc4a2ed1a4eb5b590b3ed0
+  metadata.gz: 29a78c0f4c5e3ab3afdc4245ab4dd6d9ce7d6c4f38638901a93487e366c219c6
+  data.tar.gz: 72f3fb64d9508c28338214583b185c041362f3e8b31a138ab9990cba4669b27a
 SHA512:
-  metadata.gz: 5b4acddc1c8237754644b1e75b9b11d87364e0ef2d5fac59e9ce5685464dcab180817e130a0b244cf27ac3716d0c9e1e6f78192b031a229b42cc1157117aea70
-  data.tar.gz: cf0daf98117cf7408bb1b8f3e33006043a0cd3c7f17da6f0521d98b2ebf5788be88defc0e6909ed00101a1f3a9023dbfb3cc9879b86c79193fc6750d8f6022f9
+  metadata.gz: e0b0766224a375477115ff004467b4b5196689bff28846efabd31f078bd7f36d00a5f736e088f0a8333327d9eb6f8d80e398365e79d26e99f6303e2975b66c1c
+  data.tar.gz: 69dbc6bc3859bad4e3d67c2d2131b48c41c659e79c2f9b8b0f3250fb15cb94a3c29cc0b10c217fd1b354784ac969f2d82d9be256f59e5f0224d4d597b94ea131

data/README.md

@@ -6,32 +6,38 @@
 [![Gitter Chat](https://badges.gitter.im/red-data-tools/en.svg)](https://gitter.im/red-data-tools/en)
 [![Docs Latest](https://img.shields.io/badge/docs-latest-blue.svg)](https://rubydoc.info/gems/ruby-gr)
 
-<p align="center">
-  <img src="https://user-images.githubusercontent.com/5798442/70857099-13d57600-1f2c-11ea-8f3c-7d81065f13a5.png">
-</p>
-
-:bar_chart:  [GR framework](https://github.com/sciapp/gr) - the graphics library for visualization - for Ruby
+![rdatasets-1](https://i.imgur.com/XEQ6wKs.png)
+![stem](https://i.imgur.com/3w0Ejrm.png)
+![histogram](https://i.imgur.com/xUdoA2s.png)
+![barplot](https://i.imgur.com/52bOFKE.png)
+![scatter3](https://i.imgur.com/yTTVetQ.png)
+![volume](https://i.imgur.com/CuRN6oC.png)
+![griddata](https://i.imgur.com/58HdYDo.png)
+![2darray](https://i.imgur.com/aKR2FJG.png)
+![2dpolararray](https://i.imgur.com/cmSrxvS.png)
+![hexbin](https://i.imgur.com/unWhQHr.png)
+![rdatasets-2](https://i.imgur.com/ZPit2F5.png)
+![rdatasets-3](https://i.imgur.com/TbNoxwy.png)
+![surface](https://i.imgur.com/sWdaHme.png)
+![face](https://i.imgur.com/uLCKi2r.png)
+![shade](https://i.imgur.com/VJmS3EQ.png)
+
+:bar_chart:  [GR framework](https://github.com/sciapp/gr) - powerful visualization library - for Ruby
 
 ## Installation
 
 GR.rb supports Ruby 2.4+.
 
-[Install GR](#gr-installation).
-
-Set environment variable GRDIR, if you have not already done. 
+First, [install GR](#gr-installation). Next, set environment variable `GRDIR`. 
 
 ```sh
 export GRDIR="/your/path/to/gr"
 ```
 
-Add this line to your application's Gemfile:
-
 ```sh
-gem 'ruby-gr'
+gem install ruby-gr
 ```
 
-GR3 and GR::Plot require [numo-narray](https://github.com/ruby-numo/numo-narray).
-
 ## Quick Start
 
 <p align="center">
@@ -47,42 +53,103 @@ y = [0.3, 0.5, 0.4, 0.2, 0.6, 0.7]
 GR.plot(x, y)
 ```
 
-## Examples
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/5798442/84570709-242ab880-adca-11ea-9099-3a6b3418bf19.png">
+</p>
+
+```ruby
+require 'gr/plot'
+
+x  = Numo::DFloat.linspace(0, 10, 101)
+y1 = Numo::NMath.sin(x)
+y2 = Numo::NMath.cos(x)
+
+GR.plot(
+  [x, y1, 'bo'], [x, y2, 'g*'],
+  title:    "Multiple plot example",
+  xlabel:   "x",
+  ylabel:   "y",
+  ylim:     [-1.2, 1.2],
+  labels:   ["sin(x)", "cos(x)"],
+  location: 11
+)
+```
+
+Save in PNG format.
 
-Have a look in the [`examples`](https://github.com/red-data-tools/GR.rb/tree/master/examples) directory. Start with [`fast_plot`](https://github.com/red-data-tools/GR.rb/blob/master/examples/fast_plots.rb).
+```ruby
+GR.savefig("figure.png")
+```
 
-## Features
+## API Overview
 
-#### GR::Plot
+There are two different approaches to plotting with GR.rb. One way is to call Matlab-like APIs. The other is to call GR/GR3 native functions. We are planning to prepare a more object-oriented interface based on [GRUtils.jl](https://github.com/heliosdrm/GRUtils.jl) in the future.
 
-A simple, matlab-style API.
+#### GR::Plot - A simple, matlab-style API. 
 
 ```ruby
 require 'gr/plot'
+GR.plot(x, y)
 ```
 
-`plot` `step` `scatter` `stem` `histogram` `contour` `contourf` `hexbin` `heatmap` `wireframe` `surface` `plot3` `scatter3` `imshow` `isosurface` `polar` `polarhist` `polarheatmap` `trisurf` `tricont` `shade` `volume`
-
-#### GR
+List of vailable functions. See [GR.rb Wiki](https://github.com/red-data-tools/GR.rb/wiki) for details.
+
+[`plot`](../../wiki/Plotting-functions#plot)
+[`step`](../../wiki/Plotting-functions#step)
+[`plot3`](../../wiki/Plotting-functions#plot3)
+[`polar`](../../wiki/Plotting-functions#polar)
+[`scatter`](../../wiki/Plotting-functions#scatter)
+[`scatter3`](../../wiki/Plotting-functions#scatter3)
+[`stem`](../../wiki/Plotting-functions#stem)
+[`barplot`](../../wiki/Plotting-functions#barplot)
+[`histogram`](../../wiki/Plotting-functions#histogram)
+[`polarhistogram`](../../wiki/Plotting-functions#polarhistogram)
+[`hexbin`](../../wiki/Plotting-functions#hexbin)
+[`contour`](../../wiki/Plotting-functions#contour)
+[`contourf`](../../wiki/Plotting-functions#contourf)
+[`tricont`](../../wiki/Plotting-functions#tricont)
+[`surface`](../../wiki/Plotting-functions#surface)
+[`trisurf`](../../wiki/Plotting-functions#trisurf)
+[`wireframe`](../../wiki/Plotting-functions#wireframe)
+[`volume`](../../wiki/Plotting-functions#volume)
+[`heatmap`](../../wiki/Plotting-functions#heatmap)
+[`polarheatmap`](../../wiki/Plotting-functions#polarheatmap)
+[`shade`](../../wiki/Plotting-functions#shade)
+[`imshow`](../../wiki/Plotting-functions#imshow)
+[`isosurface`](../../wiki/Plotting-functions#isosurface)
+
+#### GR - A module for calling native GR functions.
+
+2-D Plots and common 3-D Plots.
 
 ```ruby
 require 'gr'
+
+# For example
+GR.setviewport(0.1, 0.9, 0.1, 0.9)
+GR.setwindow(0.0, 20.0, 0.0, 20.0)
 ```
 
-#### GR3
+#### GR3 - A module for calling native GR3 functions.
+
+Complex 3D scenes.
 
 ```ruby
 require 'gr3'
+
+# For example
+GR3.cameralookat(-3, 2, -2, 0, 0, 0, 0, 0, -1)
 ```
 
 ## Documentation
 
+- [GR.rb Wiki](https://github.com/red-data-tools/GR.rb/wiki)
 - [GR Framework](https://gr-framework.org/)
 - [GR.rb API Documentation](https://rubydoc.info/gems/ruby-gr)
 
 ## GR Installation
 
-### Official binary release
+### Installing an official release (recommended)
 
 Download the [latest release](https://github.com/sciapp/gr/releases).
 
@@ -92,23 +159,36 @@ Set environment variable GRDIR.
 export GRDIR="your/path/to/gr"
 ```
 
-### Homebrew
+* macOS Catalina and macOS Mojave: See the "How to open an app that hasn’t been notarized or is from an unidentified developer" section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491) in the Apple documentation.
+
+### Using your package manager
+
+* The third party GR packages for Mac, Linux and Windows are available (for advanced users).
+* If you find any problem, please report the issue [here](https://github.com/red-data-tools/GR.rb/issues).
+
+#### Mac - Homebrew
 
 ```sh
 brew install libgr
 ```
 
-Set environment variable GRDIR.
+Set environment variable `GRDIR`.
 
 ```sh
 export GRDIR=$(brew --prefix libgr)
 ```
 
-If you fail to build libgr using homebrew, Please feel free to [send us your feedback](https://github.com/red-data-tools/GR.rb/issues).
+#### Linux - APT Yum
+
+[packages.red-data-tools.org](https://github.com/red-data-tools/packages.red-data-tools.org) provides `libgr-dev` and `libgr3-dev`.
+
+#### Windows - MSYS2
+
+If you are using Rubyinstaller, pacman will automatically install [mingw-w64-gr](https://packages.msys2.org/base/mingw-w64-gr) when the gem is installed.
 
 ## Backend for Charty
 
-GR.rb is expected to be the backend for [Charty](https://github.com/red-data-tools/charty) in the future.
+GR.rb will be the default backend for [Charty](https://github.com/red-data-tools/charty).
 
 ## Contributing
 
@@ -116,8 +196,9 @@ GR.rb is expected to be the backend for [Charty](https://github.com/red-data-too
 * Fix bugs and submit pull requests
 * Write, clarify, or fix documentation
 * Suggest or add new features
+* Create visualization library based on GR.rb
 
 ## Acknowledgements
 
-We would like to thank Josef Heinen, the creator of [GR.jl](https://github.com/jheinen/GR.jl) and Florian Rhiem, the creator of  [python-gr](https://github.com/sciapp/python-gr).
+We would like to thank Josef Heinen, the creator of [GR.jl](https://github.com/jheinen/GR.jl), Florian Rhiem, the creator of  [python-gr](https://github.com/sciapp/python-gr), and [GR](https://github.com/sciapp/gr) developers.
 

data/lib/gr.rb

@@ -2,40 +2,46 @@
 
 # OverView of GR.rb
 #
-#                            +--------------------+
-#     +-------------------+  | GR3 module         |
-#     | GR module         |  | +----------------+ |
-#     | +---------------+ |  | | GR3::FFI       | |
-#     | | GR::FFI       | |  | | +    libGR3.so | |
-#     | | +   libGR.so  | |  | +----------------+ |
-#     | +---------------+ |  |   | define_method  |
-#     |   | define_method |  | +----------------+ |
-#     | +---------------+ |  | | | GR3::GR3Base | |
-#     | | | GR::GRBase  | |  | | v  (Private)   | |
-#     | | v  (Private)  | |  | +++--------------+ |
-#     | +++-------------+ |  |  | Extend          |
-#     |  | Extend         |  |  v        +------+ |
-#     |  v                |  |           |Check | |
-#     |                   |  |        <--+Error | |
-#     +-------+-----------+  |           +------+ |
-#             ^              +---------+----------+
-#             |  +------------------+  ^
-#      Extend |  | GRCommons module |  | Extend
-#             |  | +--------------+ |  |
-#             |  | |    Fiddley   | |  |
-#             |  | +--------------+ |  |
-#             |  | +--------------+ |  |
-#             +----+ CommonUtils  +----+
-#             |  | +--------------+ |  |
-#             |  | +--------------+ |  |
-#             +----+    Version   +----+
-#             |  | +--------------+ |
-#             |  | +--------------+ |
-#             +----+JupyterSupport| |
-#                | +--------------+ |
-#                +------------------+
+#  +--------------------+  +--------------------+
+#  | GR module          |  | GR3 module         |
+#  | +----------------+ |  | +----------------+ |
+#  | | GR::FFI        | |  | | GR3::FFI       | |
+#  | | +   libGR.so   | |  | | +    libGR3.so | |
+#  | +----------------+ |  | +----------------+ |
+#  |   | define_method  |  |   | define_method  |
+#  | +----------------+ |  | +----------------+ |
+#  | | | GR::GRBase   | |  | | | GR3::GR3Base | |
+#  | | v  (Pri^ate)   | |  | | v  (Pri^ate)   | |
+#  | +++--------------+ |  | +++--------------+ |
+#  |  | Extend          |  |  | Extend          |
+#  |  v                 |  |  v       +-------+ |
+#  |      +-----------+ |  |          | Check | |
+#  |      | GR::Plot  | |  |       <--+ Error | |
+#  |      +-----------+ |  |          +-------+ |
+#  +--------------------+  +----------+---------+
+#            ^                        ^
+#            |  +------------------+  |
+#     Extend |  | GRCommons module |  | Extend
+#            |  | +--------------+ |  |
+#            |  | |    Fiddley   | |  |
+#            |  | +--------------+ |  |
+#            |  | +--------------+ |  |
+#            +----+ CommonUtils  +----+
+#            |  | +--------------+ |  |
+#            |  | +--------------+ |  |
+#            +----+    Version   +----+
+#            |  | +--------------+ |
+#            |  | +--------------+ |
+#            +----+JupyterSupport| |
+#               | +--------------+ |
+#               +------------------+
+#
+# (You can edit the above AA diagram with http://asciiflow.com/))
+#
+# Fiddley is Ruby-FFI compatible API layer for Fiddle.
 #
 # The GR module works without Numo::Narrray.
+# GR3 and GR::Plot depends on numo-narray.
 #
 # This is a procedural interface to the GR plotting library,
 # https://github.com/sciapp/gr
@@ -46,20 +52,24 @@ module GR
     attr_accessor :ffi_lib
   end
 
-  raise Error, 'Please set env variable GRDIR' unless ENV['GRDIR']
-
   # Platforms |  path
   # Windows   |  bin/libgr.dll
   # MacOSX    |  lib/libGR.so (NOT .dylib)
   # Ubuntu    |  lib/libGR.so
   if Object.const_defined?(:RubyInstaller)
+    ENV['GRDIR'] ||= [
+      RubyInstaller::Runtime.msys2_installation.msys_path,
+      RubyInstaller::Runtime.msys2_installation.mingwarch
+    ].join(File::ALT_SEPARATOR)
     self.ffi_lib = File.expand_path('bin/libgr.dll', ENV['GRDIR'])
     RubyInstaller::Runtime.add_dll_directory(File.dirname(ffi_lib))
   else
+    raise Error, 'Please set env variable GRDIR' unless ENV['GRDIR']
+
     self.ffi_lib = File.expand_path('lib/libGR.so', ENV['GRDIR'])
   end
 
-  # Change the default encoding to UTF-8
+  # Change the default encoding to UTF-8.
   ENV['GKS_ENCODING'] ||= 'utf8'
 
   require_relative 'gr_commons/gr_commons'
@@ -67,16 +77,19 @@ module GR
   require_relative 'gr/ffi'
   require_relative 'gr/grbase'
 
+  # `inquiry` methods etc. are defined here.
+  extend GRCommons::GRCommonUtils
+
+  # Support for Jupyter Notebook / Lab.
   extend GRCommons::JupyterSupport
 
-  # `double` is the default type in GR
+  # `double` is the default type in GR.
   # A Ruby array or NArray passed to GR method is automatically converted to
-  # a FFI::MemoryPointer in the GRBase class.
+  # a Fiddley::MemoryPointer in the GRBase class.
   extend GRBase
 
   # Now you can see a lot of methods just calling super here.
-  # Why? Do they really need?
-  # Yes. They are written to help the yard generate the documentation.
+  # They are written to help the yard generate the documentation.
   class << self
     def initgr(*)
       super
@@ -230,6 +243,9 @@ module GR
     # @param dimx [Integer] X dimension of the color index array
     # @param dimy [Integer] Y dimension of the color index array
     # @param color [Array, NArray] Color index array
+    # The values for `x` and `y` are in world coordinates. `x` must contain
+    # `dimx` + 1 elements and `y` must contain `dimy` + 1 elements. The elements
+    # i and i+1 are respectively the edges of the i-th cell in X and Y direction.
     def nonuniformcellarray(x, y, dimx, dimy, color)
       raise ArgumentError unless x.length == dimx + 1 && y.length == dimy + 1
 
@@ -1579,10 +1595,10 @@ module GR
         super(npoints, x, y, ntri, triangles.ref)
       end
       if n_tri > 0
-        tri = triangles.to_str(3 * n_tri * Fiddle::SIZEOF_INT).unpack('l*') # Int32
+        tri = triangles.to_str(dim * n_tri * Fiddle::SIZEOF_INT).unpack('l*') # Int32
         # Ruby  : 0-based indexing
         # Julia : 1-based indexing
-        tri = tri.each_slice(3).to_a
+        tri = tri.each_slice(dim).to_a
         [n_tri, tri]
       else
         0
@@ -1789,31 +1805,32 @@ module GR
       end
     end
 
-    # Draw paths using given vertices and path codes.
+    # Draw paths using the given vertices and path codes.
     # @param x [Array, NArray] A list containing the X coordinates
     # @param y [Array, NArray] A list containing the Y coordinates
-    # @param codes [String] Path codes
+    # @param codes [String] A list containing the path codes
     #  The following path codes are recognized:
     #  * M, m
-    #    * moveto           x, y
+    #    * moveto                      x, y
     #  * L, l
-    #    * lineto           x, y
+    #    * lineto                      x, y
     #  * Q, q
-    #    * quadratic Bézier x1, y1  x2, y2
+    #    * quadratic Bézier            x1, x2  y1, y2
     #  * C, c
-    #    * cubic Bézier     x1, y1  x2, y2  x3, y3
-    #  * R, r
-    #    * rectangle        w, h
+    #    * cubic Bézier                x1, x2, x3  y1, y2, y3
     #  * A, a
-    #    * arc              w, h  a1, a2
+    #    * arc                         rx, a1, reserved  ry, a2, reserved
     #  * Z
-    #    * closepath        -
+    #    * close path                  -
     #  * s
-    #    * stroke           -
+    #    * stroke                      -
+    #  * s
+    #    * close path and stroke       -
     #  * f
-    #    * fill             -
-    # The values for `x` and `y` are in normalized device coordinates.
-    # The `codes` describe several patch primitives that can be used to create compound paths.
+    #    * close path and fill         -
+    #  * F
+    #    * close path, fill and stroke -
+    # See https://gr-framework.org/python-gr.html#gr.path for more details.
     def path(x, y, codes)
       n = equal_length(x, y)
       super(n, x, y, codes)
@@ -1959,22 +1976,41 @@ module GR
       end
     end
 
-    # This is an interface for REPL based languages to enable an easier way to
-    # rotate around an object.
+    # Set the camera for orthographic or perspective projection.
     # The center of the 3d window is used as the focus point and the camera is
-    # positioned relative to it, using spherical coordinates. This function can
-    # therefore also be used if the user prefers spherical coordinates to setting
-    # the direct camera position, but with reduced functionality in comparison
-    # to gr.settransformationparameters, gr.setperspectiveprojection and
-    # gr.setorthographicprojection.
-    # @param phi [Numeric] phi angle of the spherical coordinates
-    # @param theta [Numeric] theta angle of the spherical coordinates
+    # positioned relative to it, using camera distance, rotation and tilt similar
+    # to gr_setspace. This function can be used if the user prefers spherical
+    # coordinates to setting the camera position directly, but has reduced
+    # functionality in comparison to GR.settransformationparameters,
+    # GR.setperspectiveprojection and GR.setorthographicprojection.
+    # @param phi [Numeric] azimuthal angle of the spherical coordinates
+    # @param theta [Numeric] polar angle of the spherical coordinates
     # @param fov [Numeric] vertical field of view (0 or NaN for orthographic projection)
-    # @param radius [Numeric] distance between the camera and the focus point
+    # @param camera_distance [Numeric] distance between the camera and the focus point
     #   (0 or NaN for the radius of the object's smallest bounding sphere)
-    def transformationinterfaceforrepl(*)
+    def setspace3d(*)
+      super
+    end
+
+    def text3d(*)
       super
     end
+
+    def inqtext3d(x, y, z, string, axis)
+      inquiry [{ double: 16 }, { double: 16 }] do |tbx, tby|
+        super(x, y, z, string, axis, tbx, tby)
+      end
+    end
+
+    def settextencoding(*)
+      super
+    end
+
+    def inqtextencoding
+      inquiry_int do |encoding|
+        super(encoding)
+      end
+    end
   end
 
   ASF_BUNDLED    = 0
@@ -2193,6 +2229,9 @@ module GR
   XFORM_CUBIC     = 4
   XFORM_EQUALIZED = 5
 
+  ENCODING_LATIN1 = 300
+  ENCODING_UTF8 = 301
+
   UPSAMPLE_VERTICAL_DEFAULT     = 0x00000000
   UPSAMPLE_HORIZONTAL_DEFAULT   = 0x00000000
   DOWNSAMPLE_VERTICAL_DEFAULT   = 0x00000000