ruby-gr 0.0.5 → 0.0.6

data/lib/gr/plot.rb.md

@@ -0,0 +1,207 @@
+This is a memo to think about the structure of Plot/Figure. 
+
+````ruby
+
+module GR
+  # object oriented way
+  class PlotBase
+  end
+
+  class Line < PlotBase
+  end
+
+  class << self
+    def set_viewport; end
+
+    def minmax; end
+
+    def set_window; end
+
+    def draw_axes; end
+
+    def draw_polar_axes; end
+
+    def _inqtext; end
+
+    def _text; end
+
+    def draw_legend; end
+
+    def draw_colorbar; end
+
+    def colormap; end
+
+    def to_rgba; end
+
+    # Ruby is object-oriented language.
+    # Julia is more functional...
+    # def create_context
+    # end
+    # def restore_context
+    # end
+    # def figure
+    # end
+
+    # def hold
+    # end
+    # def usecolorscheme
+    # end
+
+    # Set current subplot index.
+    def subplot; end
+
+    # draw_grid
+
+    # xticks
+    # yticks
+    # zticks
+
+    # xticklabels
+    # yticklabels
+
+    def plot_img; end # should be private?
+
+    def plot_iso; end # should be private?
+
+    def plot_polar; end # should be private?
+
+    # send_meta
+
+    def plot_data; end # should be private?
+
+    def plot_args; end # should be private?
+
+    # Draw one or more line plots.
+    def plot_line; end
+    alias lineplot plot_line
+
+    # def plot_line_over oplot_line ?
+
+    # Draw one or more step or staircase plots.
+    def plot_step; end
+    alias stepplot plot_step
+    alias step plot_step
+
+    # Draw one or more scatter plots.
+    def plot_scatter; end
+    alias scatterplot plot_scatter
+    alias scatter plot_scatter
+
+    # Draw a stem plot.
+    def plot_stem; end
+    alias stemplot plot_stem
+    alias stem plot_stem
+
+    # Draw a bar plot.
+    def plot_bar; end
+    alias barplot plot_bar
+    alias bar plot_bar
+
+    def hist; end # should be private?
+
+    # Draw a histogram.
+    def plot_histgram; end
+    alias histogram plot_histgram
+
+    # Draw a polar histogram.
+    def plot_polarhistogram; end
+    alias polarhistogram plot_polarhistogram
+
+    # Draw a contour plot.
+    def plot_contour; end
+    alias contourplot plot_contour
+    # GR.contour is already defined in GR::FFI class.
+
+    # Draw a filled contour plot.
+    def plot_contourf; end
+    alias contourfplot plot_contour # change name?
+    # GR.contourf is already defined in GR::FFI class.
+
+    # Draw a hexagon binning plot.
+    def plot_hexbin; end
+    alias hexbinplot plot_hexbin
+    # GR.hexbin is already defined in GR::FFI class.
+    alias jointplot plot_hexbin
+
+    # Draw a heatmap.
+    def plot_heatmap; end
+    alias heatmap plot_heatmap
+
+    def plot_polarheatmap; end
+    alias polarheatmap plot_polarheatmap
+
+    # Draw a three-dimensional wireframe plot.
+    def plot_wireframe; end
+    alias wireframe plot_wireframe
+
+    # Draw a three-dimensional surface plot.
+    def plot_surface; end
+    alias surfaceplot plot_surface
+
+    def plot_volume; end
+    alias volumeplot plot_volume
+
+    # Draw one or more three-dimensional line plots.
+    def plot_line3; end
+    alias lineplot3 plot_line3
+
+    # Draw one or more three-dimensional scatter plots.
+    def plot_scatter3; end
+    alias scatterplot3 plot_scatter3
+
+    def redraw; end
+
+    def title; end
+
+    def xlabel; end
+
+    def ylabel; end
+
+    def legend; end
+
+    def xlim; end
+
+    def ylim; end
+
+    def savefig; end
+
+    def meshgrid; end # should be private ?
+
+    def peaks; end # should be private ?
+
+    def imshow; end
+
+    # Draw an isosurface.
+    def plot_isosurface; end
+
+    # Draw one or more polar plots.
+    def plot_polar; end
+
+    # Draw a triangular surface plot.
+    def plot_trisurf; end
+
+    # Draw a triangular contour plot.
+    def plot_tricont; end
+
+    def plot_shade; end
+
+    # def set_panzoom ?
+
+    # mainloop
+
+    # GR.plot do
+    #
+    # end
+    #
+    # GR.plot(:scatter, * * *)
+    def plot; end
+
+    # Object ?
+
+    # a = GR::Bar.new()
+    # a.draw ?
+    # a = GR::Bar.plot() ?
+  end
+end
+
+```

data/lib/gr3.rb

@@ -2,38 +2,52 @@
 
 # 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
-#         |  | +--------------+ |  |
-#         +----+ CommonUtils  +----+
-#         |  | +--------------+ |  |
-#         |  | +--------------+ |  |
-#         +----+    Version   +----+
-#         |  | +--------------+ |
-#         |  | +--------------+ |
-#         +----+JupyterSupport| |
-#            | +--------------+ |
-#            +------------------+
-
-require 'ffi'
-
+#                            +--------------------+
+#     +-------------------+  | 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| |
+#                | +--------------+ |
+#                +------------------+
+#
+# Why not GR::GR3?
+# * kojix2 did not want to force gr3 to be loaded when gr is loaded.
+# * kojix2 did not want to write `GR3 = GR::GR3` or something.
+# * This is a opinion of kojix2 and may be changed in the future.
+#
+# GR3 uses Numo::Narrray.
+# * It is difficult to write GR3 modules with only Ruby arrays.
+# * Numo::Narray has better performance and is easier to read.
+# * Numo::Narray does not work with JRuby.
+#   * https://github.com/ruby-numo/numo-narray/issues/147
+#
+# This is a procedural interface to the GR3 in GR plotting library,
+# https://github.com/sciapp/gr
 module GR3
   class Error < StandardError; end
 
@@ -42,19 +56,18 @@ module GR3
   end
 
   # Platforms |  path
-  # Windows   |  bin/libgr3.dll
+  # Windows   |  bin/libGR3.dll
   # MacOSX    |  lib/libGR3.so (NOT .dylib)
   # Ubuntu    |  lib/libGR3.so
   raise Error, 'Please set env variable GRDIR' unless ENV['GRDIR']
 
   ENV['GKS_FONTPATH'] ||= ENV['GRDIR']
-  @ffi_lib = case RbConfig::CONFIG['host_os']
-             when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-               File.expand_path('bin/libgr3.dll', ENV['GRDIR'])
-                   .gsub('/', '\\') # windows backslash
-             else
-               File.expand_path('lib/libGR3.so', ENV['GRDIR'])
-             end
+  if Object.const_defined?(:RubyInstaller)
+    @ffi_lib = File.expand_path('bin/libGR3.dll', ENV['GRDIR'])
+    RubyInstaller::Runtime.add_dll_directory(File.dirname(@ffi_lib))
+  else
+    @ffi_lib = File.expand_path('lib/libGR3.so', ENV['GRDIR'])
+  end
 
   require_relative 'gr_commons'
   require_relative 'gr3/version'
@@ -69,13 +82,14 @@ module GR3
   # This module is for adding error checking to all methods in GR3
   module CheckError
     def geterror
-      line = ::FFI::MemoryPointer.new(:int)
-      file = ::FFI::MemoryPointer.new(:pointer)
+      line = GRCommons::Fiddley::MemoryPointer.new(:int)
+      file = GRCommons::Fiddley::MemoryPointer.new(:pointer)
       e = super(1, line, file)
       return [0, nil, nil] if e == 0
 
       line = line.read_int
-      file = file.read_pointer.read_string
+      # to_ptr: Fiddley::MemoryPointer -> Fiddle::Pointer
+      file = file.to_ptr.ptr.to_s
       [e, line, file]
     end
 
@@ -90,11 +104,15 @@ module GR3
           mesg = FFI.gr3_geterrorstring(e)
           raise "GR3 error #{file} #{line} #{mesg}"
         end
+        values
       end
     end
   end
   extend CheckError
 
+  # 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.
   class << self
     # This method initializes the gr3 context.
     # @return [Integer]
@@ -124,13 +142,13 @@ module GR3
     # If gr3 is not initialized `"Not initialized"` is returned.
     # @return [String]
     def getrenderpathstring(*)
-      super
+      super.to_s
     end
 
     # This function returns a string representation of a given error code.
     # @return [String]
     def geterrorstring(*)
-      super
+      super.to_s
     end
 
     # This function clears the draw list.
@@ -366,9 +384,9 @@ module GR3
     # a new mesh has to be created.
     # @param nx [Integer] number of points in x-direction
     # @param ny [Integer] number of points in y-direction
-    # @param px [Array, NArray] an array containing the x-coordinates
-    # @param py [Array, NArray] an array containing the y-coordinates
-    # @param pz [Array, NArray] an array of length nx * ny containing the z-coordinates
+    # @param x [Array, NArray] an array containing the x-coordinates
+    # @param y [Array, NArray] an array containing the y-coordinates
+    # @param z  [Array, NArray] an array of length nx * ny containing the z-coordinates
     # @param option [Integer] option for the surface mesh; the GR3_SURFACE constants can be combined with bitwise or. See the table below.
     #  * 0  : GR3_SURFACE_DEFAULT
     #    *    default behavior
@@ -383,9 +401,9 @@ module GR3
     #  * 16 : GR3_SURFACE_GRZSHADED
     #    *    like GR3_SURFACE_GRCOLOR, but use the z-value directly as color index
     # @return [Integer]
-    def createsurfacemesh(nx, ny, px, py, pz, option = 0)
+    def createsurfacemesh(nx, ny, x, y, z, option = 0)
       inquiry_int do |mesh|
-        super(mesh, nx, ny, px, py, pz, option)
+        super(mesh, nx, ny, x, y, z, option)
       end
     end
 
@@ -413,16 +431,16 @@ module GR3
     end
 
     # Create a surface plot with gr3 and draw it with gks as cellarray.
-    # @param px [Array, NArray] an array containing the x-coordinates
-    # @param py [Array, NArray] an array containing the y-coordinates
-    # @param pz [Array, NArray] an array of length nx * ny containing the z-coordinates
+    # @param x [Array, NArray] an array containing the x-coordinates
+    # @param y [Array, NArray] an array containing the y-coordinates
+    # @param z  [Array, NArray] an array of length nx * ny containing the z-coordinates
     # @param option [Integer] see the option parameter of gr_surface.
     #  OPTION_COLORED_MESH and OPTION_Z_SHADED_MESH are supported.
-    def surface(px, py, pz, _option)
-      nx = px.length
-      ny = py.length
+    def surface(x, y, z, option)
+      nx = x.length
+      ny = y.length
       # TODO: Check out_of_bounds
-      super(nx, ny, px, py, pz, ption)
+      super(nx, ny, x, y, z, option)
     end
 
     # drawtubemesh
@@ -675,10 +693,10 @@ module GR3
 
     def volume(data, algorithm)
       inquiry %i[double double] do |dmin, dmax|
-        amin.write_double(-1)
+        dmin.write_double(-1)
         dmax.write_double(-1)
         # TODO: raise error when no NArray
-        data = Numo::DFloat.cast(data) if data.is_a Array
+        data = Numo::DFloat.cast(data) if data.is_a? Array
         nx, ny, nz = data.shape
         super(nx, ny, nz, data, algorithm, dmin, dmax)
       end
@@ -731,38 +749,38 @@ module GR3
   end
 
   # InitAttribute
-  IA_END_OF_LIST = 0
-  IA_FRAMEBUFFER_WIDTH = 1
+  IA_END_OF_LIST        = 0
+  IA_FRAMEBUFFER_WIDTH  = 1
   IA_FRAMEBUFFER_HEIGHT = 2
 
   # Error
-  ERROR_NONE = 0
-  ERROR_INVALID_VALUE = 1
-  ERROR_INVALID_ATTRIBUTE = 2
-  ERROR_INIT_FAILED = 3
-  ERROR_OPENGL_ERR = 4
-  ERROR_OUT_OF_MEM = 5
-  ERROR_NOT_INITIALIZED = 6
-  ERROR_CAMERA_NOT_INITIALIZED = 7
-  ERROR_UNKNOWN_FILE_EXTENSION = 8
-  ERROR_CANNOT_OPEN_FILE = 9
-  ERROR_EXPORT = 10
+  ERROR_NONE                   =  0
+  ERROR_INVALID_VALUE          =  1
+  ERROR_INVALID_ATTRIBUTE      =  2
+  ERROR_INIT_FAILED            =  3
+  ERROR_OPENGL_ERR             =  4
+  ERROR_OUT_OF_MEM             =  5
+  ERROR_NOT_INITIALIZED        =  6
+  ERROR_CAMERA_NOT_INITIALIZED =  7
+  ERROR_UNKNOWN_FILE_EXTENSION =  8
+  ERROR_CANNOT_OPEN_FILE       =  9
+  ERROR_EXPORT                 = 10
 
   # Quality
-  QUALITY_OPENGL_NO_SSAA  = 0
-  QUALITY_OPENGL_2X_SSAA  = 2
-  QUALITY_OPENGL_4X_SSAA  = 4
-  QUALITY_OPENGL_8X_SSAA  = 8
+  QUALITY_OPENGL_NO_SSAA  =  0
+  QUALITY_OPENGL_2X_SSAA  =  2
+  QUALITY_OPENGL_4X_SSAA  =  4
+  QUALITY_OPENGL_8X_SSAA  =  8
   QUALITY_OPENGL_16X_SSAA = 16
-  QUALITY_POVRAY_NO_SSAA  = 0 + 1
-  QUALITY_POVRAY_2X_SSAA  = 2 + 1
-  QUALITY_POVRAY_4X_SSAA  = 4 + 1
-  QUALITY_POVRAY_8X_SSAA  = 8 + 1
+  QUALITY_POVRAY_NO_SSAA  =  0 + 1
+  QUALITY_POVRAY_2X_SSAA  =  2 + 1
+  QUALITY_POVRAY_4X_SSAA  =  4 + 1
+  QUALITY_POVRAY_8X_SSAA  =  8 + 1
   QUALITY_POVRAY_16X_SSAA = 16 + 1
 
   # Drawable
   DRAWABLE_OPENGL = 1
-  DRAWABLE_GKS = 2
+  DRAWABLE_GKS    = 2
 
   # SurfaceOption
   SURFACE_DEFAULT     =  0