Class: GMT

Inherits:
Object
  • Object
show all
Defined in:
lib/gmt.rb

Overview

This class provides a native extension accessing the programs of the Generic Mapping Tools; an open source collection of about 80 command-line tools for manipulating geographic and Cartesian data sets (including filtering, trend fitting, gridding, projecting, etc.) and producing PostScript illustrations ranging from simple x–y plots via contour maps to artificially illuminated surfaces and 3D perspective views

An example of usage:

require 'gmt'

common = { file: 'output.ps', R: '0/3/0/2', J: 'x1i' }

GMT.session do |gmt|
  gmt.psxy('dots.xy',
           common.merge(
             position: :first,
             S: 'c0.50c',
             G: 'blue'))
  gmt.psxy('dots.xy',
           common.merge(
             position: :last,
             S: 'c0.25c',
             G: 'red'))
end

Those familiar with GMT will recognise the -R (range) and -J (projection) options which are now keys for the program options hash.

The session

All GMT functions (modules in the GMT parlance) require a session context, and an instance of the GMT class is exactly such a context.

gmt = GMT.new

There are no arguments for the constructor.

A session object is also yielded by the GMT.session class method:

GMT.session do |gmt|
  # do something with gmt
end

GMT functions

Each GMT function is available as instance method, and each has the same signatures: several arguments, typically input files, followed by a single options hash. The options hash corresponds to the command-line options of the GMT program; hence the shell command

gmt makecpt -Cgebco depths.txt -i2 -Z -E24 > my_depths.cpt

would be replicated by the Ruby

gmt = GMT.new
gmt.makecpt('depths.txt',
            C: 'gebco', i: 2, Z: nil, E: 24, :> => 'my_depths.cpt')

Note that

  • the argument(s) (the input file 'depths.txt') preceed(s) the options hash

  • the options hash has keys which are symbols

  • options which lack arguments correspond to hash keys with nil values :Z => nil.

  • the output redirection is also treated as hash option, with key :> and value which is the output file.

The options without argument can also be specifed by a symbol argument, but recall that arguments must proceed the options hash, so the above would be

gmt.makecpt('depths.txt',
            :Z, C: 'gebco', i: 2, E: 24, :> => 'my_depths.cpt')

using this format.

PostScript functions

When creating complex PostScript plots one needs to make several calls to GMT functions, to use the -O and -K options, and to append output of the second and subsequent calls (rather than overwriting). This is tiresome and error-prone on the command-line, and more so in the “options hash” representation in the Ruby module.

So we add some syntatactic sugar for these PostScript functions: if the options hash has the keys :position (with values one of :first, :middle, or :last) and :file (with the value of the ouptut file), then the -O and -K options and the output redirection are handled by the class. So one might write

gmt = GMT.new
gmt.psbasemap(

Constant Summary collapse

VERSION_MAJOR =

version constants

INT2NUM(GMT_MAJOR_VERSION)
VERSION_MINOR = 
INT2NUM(GMT_MINOR_VERSION)
VERSION_RELEASE = 
INT2NUM(GMT_RELEASE_VERSION)

Filtering of 1-D and 2-D Data collapse

Plotting of 1-D and 2-D Data collapse

Gridding of Data Tables collapse

Sampling of 1-D and 2-D Data collapse

Projection and Map-transformation collapse

Retrieve Information collapse

Mathematical Operations on Tables or Grids collapse

Convert or Extract Subsets of Data collapse

Determine Trends in 1-D and 2-D Data collapse

Other Operations on 2-D Grids collapse

Miscellaneous Tools collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Object 



54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'ext/gmt/gmt.c', line 54

static VALUE gmt_init(VALUE self)
{
  gmt_t *gmt;

  Data_Get_Struct(self, gmt_t, gmt);

  gmt->session =
    GMT_Create_Session("Session name", 2, 0, NULL);

  if (gmt->session == NULL)
    rb_raise(rb_eNoMemError, "failed to create GMT session");

  return self;
}

Class Method Details

.session {|gmt| ... } ⇒ Object

Yields:

  • (gmt) —

    yields the GMT session to the block



172
173
174
175
176
 
# File 'lib/gmt.rb', line 172

def session
  gmt = GMT.new
  yield gmt
  gmt.free
end

.version_at_least?(major, minor = 0, release = 0) ⇒ Boolean

Returns true if the current API version is at least as requested.

Examples:

If the current API version if 5.3.2, then

GMT.version_at_least?(5) #=> true
GMT.version_at_least?(5, 3, 1) #=> true
GMT.version_at_least?(5, 3, 3) #=> false



112
113
114
115
116
117
118
119
120
 
# File 'lib/gmt.rb', line 112

def version_at_least?(major, minor=0, release=0)
  if VERSION_MAJOR > major then
    true
  elsif VERSION_MAJOR < major then
    false
  else
    version_at_least_minor?(minor, release)
  end
end

Instance Method Details

#blockmean(*arguments, **options) ⇒ Boolean

L2 (x,y,z) table data filter/decimator

See Also:



263
 
# File 'lib/gmt.rb', line 263

wrapper_other :blockmean

#blockmedian(*arguments, **options) ⇒ Boolean

L1 (x,y,z) table data filter/decimator

See Also:



266
 
# File 'lib/gmt.rb', line 266

wrapper_other :blockmedian

#blockmode(*arguments, **options) ⇒ Boolean

Mode estimate (x,y,z) table data filter/decimator

See Also:



269
 
# File 'lib/gmt.rb', line 269

wrapper_other :blockmode

#filter1d(*arguments, **options) ⇒ Boolean

Time domain filtering of 1-D data tables

See Also:



272
 
# File 'lib/gmt.rb', line 272

wrapper_other :filter1d

#fitcircle(*arguments, **options) ⇒ Boolean

Finds the best-fitting great or small circle for a set of points

See Also:



473
 
# File 'lib/gmt.rb', line 473

wrapper_other :fitcircle

#free ⇒ Object 



69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'ext/gmt/gmt.c', line 69

static VALUE gmt_release(VALUE self)
{
  gmt_t *gmt;

  Data_Get_Struct(self, gmt_t, gmt);

  if (gmt->session)
    {
      GMT_Destroy_Session(gmt->session);
      gmt->session = NULL;
    }

  return self;
}

#gmt2kml(*arguments, **options) ⇒ Boolean

Like psxy but plots KML for use in Google Earth

See Also:



521
 
# File 'lib/gmt.rb', line 521

wrapper_other :gmt2kml

#gmtconnect(*arguments, **options) ⇒ Boolean

Connect segments into more complete lines or polygons

See Also:



431
 
# File 'lib/gmt.rb', line 431

wrapper_other :gmtconnect

#gmtconvert(*arguments, **options) ⇒ Boolean

Convert data tables from one format to another

See Also:



434
 
# File 'lib/gmt.rb', line 434

wrapper_other :gmtconvert

#gmtdefaults(*arguments, **options) ⇒ Boolean

List the current default settings

See Also:



392
 
# File 'lib/gmt.rb', line 392

wrapper_other :gmtdefaults

#gmtget(*arguments, **options) ⇒ Boolean

Retrieve selected parameters in current file

See Also:



395
 
# File 'lib/gmt.rb', line 395

wrapper_other :gmtget

#gmtinfo(*arguments, **options) ⇒ Boolean

Get information about table data files

See Also:



398
 
# File 'lib/gmt.rb', line 398

wrapper_other :gmtinfo

#gmtlogo(*files, **options) ⇒ Boolean

Plot the GMT logo on maps

A PostScript function (accepts :file and :position options).

See Also:



281
 
# File 'lib/gmt.rb', line 281

wrapper_ps :gmtlogo

#gmtmath(*arguments, **options) ⇒ Boolean

Mathematical operations on table data

See Also:



410
 
# File 'lib/gmt.rb', line 410

wrapper_other :gmtmath

#gmtregress(*arguments, **options) ⇒ Boolean

Linear regression of 1-D data sets

See Also:



476
 
# File 'lib/gmt.rb', line 476

wrapper_other :gmtregress

#gmtselect(*arguments, **options) ⇒ Boolean

Select subsets of table data based on multiple spatial criteria

See Also:



437
 
# File 'lib/gmt.rb', line 437

wrapper_other :gmtselect

#gmtset(*arguments, **options) ⇒ Boolean

Change selected parameters in current file

See Also:



401
 
# File 'lib/gmt.rb', line 401

wrapper_other :gmtset

#gmtsimplify(*arguments, **options) ⇒ Boolean

Line reduction using the Douglas-Peucker algorithm

See Also:



365
 
# File 'lib/gmt.rb', line 365

wrapper_other :gmtsimplify

#gmtspatial(*arguments, **options) ⇒ Boolean

Geospatial operations on lines and polygons

See Also:



440
 
# File 'lib/gmt.rb', line 440

wrapper_other :gmtspatial

#gmtvector(*arguments, **options) ⇒ Boolean

Operations on Cartesian vectors in 2-D and 3-D

See Also:



443
 
# File 'lib/gmt.rb', line 443

wrapper_other :gmtvector

#grd2cpt(*arguments, **options) ⇒ Boolean

Make color palette table from a grid files

See Also:



488
 
# File 'lib/gmt.rb', line 488

wrapper_other :grd2cpt

#grd2rgb(*arguments, **options) ⇒ Boolean

Convert Sun raster or grid file to red, green, blue component grids

See Also:



446
 
# File 'lib/gmt.rb', line 446

wrapper_other :grd2rgb

#grd2xyz(*arguments, **options) ⇒ Boolean

Conversion from 2-D grid file to table data

See Also:



449
 
# File 'lib/gmt.rb', line 449

wrapper_other :grd2xyz

#grdblend(*arguments, **options) ⇒ Boolean

Blend several partially over-lapping grid files onto one grid

See Also:



452
 
# File 'lib/gmt.rb', line 452

wrapper_other :grdblend

#grdclip(*arguments, **options) ⇒ Boolean

Limit the z-range in gridded data sets

See Also:



491
 
# File 'lib/gmt.rb', line 491

wrapper_other :grdclip

#grdcontour(*files, **options) ⇒ Boolean

Contouring of 2-D gridded data sets

A PostScript function (accepts :file and :position options).

See Also:



284
 
# File 'lib/gmt.rb', line 284

wrapper_ps :grdcontour

#grdconvert(*arguments, **options) ⇒ Boolean

Converts grid files into other grid formats

See Also:



455
 
# File 'lib/gmt.rb', line 455

wrapper_other :grdconvert

#grdcut(*arguments, **options) ⇒ Boolean

Cut a sub-region from a grid file

See Also:



458
 
# File 'lib/gmt.rb', line 458

wrapper_other :grdcut

#grdedit(*arguments, **options) ⇒ Boolean

Modify header information in a 2-D grid file

See Also:



494
 
# File 'lib/gmt.rb', line 494

wrapper_other :grdedit

#grdfft(*arguments, **options) ⇒ Boolean

Perform operations on grid files in the frequency domain

See Also:



497
 
# File 'lib/gmt.rb', line 497

wrapper_other :grdfft

#grdfilter(*arguments, **options) ⇒ Boolean

Filter 2-D gridded data sets in the space domain

See Also:



275
 
# File 'lib/gmt.rb', line 275

wrapper_other :grdfilter

#grdgradient(*arguments, **options) ⇒ Boolean

Compute directional gradient from grid files

See Also:



500
 
# File 'lib/gmt.rb', line 500

wrapper_other :grdgradient

#grdhisteq(*arguments, **options) ⇒ Boolean

Histogram equalization for grid files

See Also:



503
 
# File 'lib/gmt.rb', line 503

wrapper_other :grdhisteq

#grdimage(*files, **options) ⇒ Boolean

Produce images from 2-D gridded data sets

A PostScript function (accepts :file and :position options).

See Also:



287
 
# File 'lib/gmt.rb', line 287

wrapper_ps :grdimage

#grdinfo(*arguments, **options) ⇒ Boolean

Get information about grid files

See Also:



404
 
# File 'lib/gmt.rb', line 404

wrapper_other :grdinfo

#grdlandmask(*arguments, **options) ⇒ Boolean

Create masking grid files from shoreline data base

See Also:



506
 
# File 'lib/gmt.rb', line 506

wrapper_other :grdlandmask

#grdmask(*arguments, **options) ⇒ Boolean

Reset grid nodes in/outside a clip path to constants

See Also:



509
 
# File 'lib/gmt.rb', line 509

wrapper_other :grdmask

#grdmath(*arguments, **options) ⇒ Boolean

Mathematical operations on grid files

See Also:



512
 
# File 'lib/gmt.rb', line 512

wrapper_other :grdmath

#grdpaste(*arguments, **options) ⇒ Boolean

Paste together grid files along a common edge

See Also:



461
 
# File 'lib/gmt.rb', line 461

wrapper_other :grdpaste

#grdproject(*arguments, **options) ⇒ Boolean

Project gridded data sets onto a new coordinate system

See Also:



380
 
# File 'lib/gmt.rb', line 380

wrapper_other :grdproject

#grdsample(*arguments, **options) ⇒ Boolean

Resample a 2-D gridded data set onto a new grid

See Also:



368
 
# File 'lib/gmt.rb', line 368

wrapper_other :grdsample

#grdtrack(*arguments, **options) ⇒ Boolean

Sampling of 2-D gridded data set(s) along 1-D track

See Also:



371
 
# File 'lib/gmt.rb', line 371

wrapper_other :grdtrack

#grdvector(*files, **options) ⇒ Boolean

Plotting of 2-D gridded vector fields

A PostScript function (accepts :file and :position options).

See Also:



290
 
# File 'lib/gmt.rb', line 290

wrapper_ps :grdvector

#grdview(*files, **options) ⇒ Boolean

3-D perspective imaging of 2-D gridded data sets

A PostScript function (accepts :file and :position options).

See Also:



293
 
# File 'lib/gmt.rb', line 293

wrapper_ps :grdview

#grdvolume(*arguments, **options) ⇒ Boolean

Calculate volumes under a surface within specified contour

See Also:



515
 
# File 'lib/gmt.rb', line 515

wrapper_other :grdvolume

#greenspline(*arguments, **options) ⇒ Boolean

Interpolation with Green’s functions for splines in 1–3 D

See Also:



347
 
# File 'lib/gmt.rb', line 347

wrapper_other :greenspline

#kml2gmt(*arguments, **options) ⇒ Boolean

Extracts coordinates from Google Earth KML files

See Also:



524
 
# File 'lib/gmt.rb', line 524

wrapper_other :kml2gmt

#makecpt(*arguments, **options) ⇒ Boolean

Make color palette tables

See Also:



413
 
# File 'lib/gmt.rb', line 413

wrapper_other :makecpt

#mapproject(*arguments, **options) ⇒ Boolean

Transformation of coordinate systems for table data

See Also:



383
 
# File 'lib/gmt.rb', line 383

wrapper_other :mapproject

#nearneighbor(*arguments, **options) ⇒ Boolean

Nearest-neighbor gridding scheme

See Also:



350
 
# File 'lib/gmt.rb', line 350

wrapper_other :nearneighbor

#project(*arguments, **options) ⇒ Boolean

Project table data onto lines or great circles

See Also:



386
 
# File 'lib/gmt.rb', line 386

wrapper_other :project

#psbasemap(*files, **options) ⇒ Boolean

Create a basemap plot

A PostScript function (accepts :file and :position options).

See Also:



296
 
# File 'lib/gmt.rb', line 296

wrapper_ps :psbasemap

#psclip(*files, **options) ⇒ Boolean

Use polygon files to define clipping paths

A PostScript function (accepts :file and :position options).

See Also:



299
 
# File 'lib/gmt.rb', line 299

wrapper_ps :psclip

#pscoast(*files, **options) ⇒ Boolean

Plot (and fill) coastlines, borders, and rivers on maps

A PostScript function (accepts :file and :position options).

See Also:



302
 
# File 'lib/gmt.rb', line 302

wrapper_ps :pscoast

#pscontour(*files, **options) ⇒ Boolean

Contour or image raw table data by triangulation

A PostScript function (accepts :file and :position options).

See Also:



305
 
# File 'lib/gmt.rb', line 305

wrapper_ps :pscontour

#psconvert(*arguments, **options) ⇒ Boolean

Crop and convert PostScript files to raster images, EPS, and PDF

See Also:



527
 
# File 'lib/gmt.rb', line 527

wrapper_other :psconvert

#pshistogram(*files, **options) ⇒ Boolean

Plot a histogram

A PostScript function (accepts :file and :position options).

See Also:



308
 
# File 'lib/gmt.rb', line 308

wrapper_ps :pshistogram

#psimage(*files, **options) ⇒ Boolean

Plot Sun raster files on a map

A PostScript function (accepts :file and :position options).

See Also:



311
 
# File 'lib/gmt.rb', line 311

wrapper_ps :psimage

#pslegend(*files, **options) ⇒ Boolean

Plot a legend on a map

A PostScript function (accepts :file and :position options).

See Also:



314
 
# File 'lib/gmt.rb', line 314

wrapper_ps :pslegend

#psmask(*files, **options) ⇒ Boolean

Create overlay to mask out regions on maps

A PostScript function (accepts :file and :position options).

See Also:



317
 
# File 'lib/gmt.rb', line 317

wrapper_ps :psmask

#psrose(*files, **options) ⇒ Boolean

Plot sector or rose diagrams

A PostScript function (accepts :file and :position options).

See Also:



320
 
# File 'lib/gmt.rb', line 320

wrapper_ps :psrose

#psscale(*files, **options) ⇒ Boolean

Plot gray scale or color scale on maps

A PostScript function (accepts :file and :position options).

See Also:



323
 
# File 'lib/gmt.rb', line 323

wrapper_ps :psscale

#pssolar(*files, **options) ⇒ Boolean

Calculate and plot the day-night terminator

A PostScript function (accepts :file and :position options).

See Also:



338
 
# File 'lib/gmt.rb', line 338

wrapper_ps :pssolar

#psternary(*files, **options) ⇒ Boolean

Plot data on ternary diagrams

A PostScript function (accepts :file and :position options).

See Also:



341
 
# File 'lib/gmt.rb', line 341

wrapper_ps :psternary

#pstext(*files, **options) ⇒ Boolean

Plot text strings on maps

A PostScript function (accepts :file and :position options).

See Also:



326
 
# File 'lib/gmt.rb', line 326

wrapper_ps :pstext

#pswiggle(*files, **options) ⇒ Boolean

Draw table data time-series along track on maps

A PostScript function (accepts :file and :position options).

See Also:



329
 
# File 'lib/gmt.rb', line 329

wrapper_ps :pswiggle

#psxy(*files, **options) ⇒ Boolean

Plot symbols, polygons, and lines on maps

A PostScript function (accepts :file and :position options).

See Also:



332
 
# File 'lib/gmt.rb', line 332

wrapper_ps :psxy

#psxyz(*files, **options) ⇒ Boolean

Plot symbols, polygons, and lines in 3-D

A PostScript function (accepts :file and :position options).

See Also:



335
 
# File 'lib/gmt.rb', line 335

wrapper_ps :psxyz

#sample1d(*arguments, **options) ⇒ Boolean

Resampling of 1-D table data sets

See Also:



374
 
# File 'lib/gmt.rb', line 374

wrapper_other :sample1d

#spectrum1d(*arguments, **options) ⇒ Boolean

Compute various spectral estimates from time-series

See Also:



416
 
# File 'lib/gmt.rb', line 416

wrapper_other :spectrum1d

#sph2grd(*arguments, **options) ⇒ Boolean

Compute grid from spherical harmonic coefficients

See Also:



419
 
# File 'lib/gmt.rb', line 419

wrapper_other :sph2grd

#sphdistance(*arguments, **options) ⇒ Boolean

Make grid of distances to nearest points on a sphere

See Also:



422
 
# File 'lib/gmt.rb', line 422

wrapper_other :sphdistance

#sphinterpolate(*arguments, **options) ⇒ Boolean

Spherical gridding in tension of data on a sphere

See Also:



353
 
# File 'lib/gmt.rb', line 353

wrapper_other :sphinterpolate

#sphtriangulate(*arguments, **options) ⇒ Boolean

Delaunay or Voronoi construction of spherical lon,lat data

See Also:



425
 
# File 'lib/gmt.rb', line 425

wrapper_other :sphtriangulate

#splitxyz(*arguments, **options) ⇒ Boolean

Split xyz files into several segments

See Also:



464
 
# File 'lib/gmt.rb', line 464

wrapper_other :splitxyz

#surface(*arguments, **options) ⇒ Boolean

A continuous curvature gridding algorithm

See Also:



356
 
# File 'lib/gmt.rb', line 356

wrapper_other :surface

#trend1d(*arguments, **options) ⇒ Boolean

Fits polynomial or Fourier trends to y = f(x) series

See Also:



479
 
# File 'lib/gmt.rb', line 479

wrapper_other :trend1d

#trend2d(*arguments, **options) ⇒ Boolean

Fits polynomial trends to z = f(x,y) series

See Also:



482
 
# File 'lib/gmt.rb', line 482

wrapper_other :trend2d

#triangulate(*arguments, **options) ⇒ Boolean

Perform optimal Delauney triangulation and gridding

See Also:



359
 
# File 'lib/gmt.rb', line 359

wrapper_other :triangulate

#xyz2grd(*arguments, **options) ⇒ Boolean

Convert an equidistant table xyz file to a 2-D grid file

See Also:



467
 
# File 'lib/gmt.rb', line 467

wrapper_other :xyz2grd