Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
499 lines (414 sloc) 17.3 KB
= module ShapeLib
This module is a wrapper of C Shapefile Library
(also called ((<ShapeLib|URL:>))).
It consists of basically two classes:
((<ShapeFile|class ShapeFile>)) and ((<Shape|class Shape>)).
If you are unfamiliar with object-oriented programming,
please see ((<Appendix A: C to Ruby equivalence table>)).
A extension library (({shapelib})) must be required before using this module:
require 'shapelib'
== module functions
Following three functions construct a point object.
It can be used like top level function after (({include})):
include ShapeLib
pt = new_point(1, 2)
Arguments ((|x|)), ((|y|)), ((|z|)), and ((|m|)) ((<should be Float>)).
--- ShapeLib.new_point x, y
creates a ((<class Point>)) object.
--- ShapeLib.new_point x, y, m
creates a ((<class PointM>)) object.
--- ShapeLib.new_point x, y, m, z
creates a ((<class PointZ>)) object.
== class ShapeFile
=== class methods
Following two class methods (({new})) and (({open}))
return an instance of ((<class ShapeFile>)) if succeeded.
Exception is raised on failure.
It is recommended to call ((<shapefile.close>))
when each shapefile is no longer used.
--- ShapeFile::open filename, access = 'rb'
--- ShapeFile::open(filename, access = 'rb') { |fp| ... }
The (({open})) method opens an existing shapefile.
Argument ((|filename|)) should be
either fullname (like "(({basename.shp}))")
or just basename (like "(({basename}))").
Suffix (({.shp})) must be lowercase if specified.
Both (({.shp})) and (({.shx})) files must exist at the specified path.
Argument ((|access|)) are passed to (({fopen(3)})) through
((<ShapeLib>)) (({SHPOpen()})) function.
Either '(({rb}))' or '(({rb+}))' should be used.
If a block is given to these constructors,
the opened shapefile object is yielded like File::open.
The shapefile is closed at the end of block,
and the constructor returns (({nil})).
# example { |fp|
print "#{filename} has #{fp.size} records.\n"
--- ShapeFile::new filename, shapetype, attrs
--- ShapeFile::new(filename, shapetype, attrs) { |fp| ... }
The (({new})) method creates a shapefile.
All three files ((({.shp})), (({.shx})), and (({.dbf}))) are created.
Argument ((|shapetype|)) specifies the ((<type of shapes>))
to be stored in the shapefile.
Argument ((|attrs|)) is an array of arrays
that specifies ((|field_name|)), ((|field_type|)), ((|width|)),
and optional ((|decimal|)) as in
((<shapefile.add_field|shapefile.add_field field_name, field_type, width, decimal = 0>))
# example
fp = ShapeFile::new('city.shp', :Point,
[['name', :String, 32],
['population', :Integer, 9],
['height', :Float, 9, 1]])
=== instance methods
--- shapefile.add_field field_name, field_type, width, decimal = 0
Adds an attribute field to the shapefile (that must be newly created by
((<ShapeFile::new|ShapeFile::new filename, shapetype, attrs>))).
Argument ((|field_name|)) is a String for field name;
((|field_type|)) specifies ((<field type>));
((|width|)) is nonnegative Integer for field width in characters; and
((|decimal|)) is nonnegative Integer for decimal points.
Only Float field requires ((|decimal|)); otherwise it can be missing.
# example
fp.add_field 'name', :String, 32
fp.add_field 'height', "Float", 9, 1
--- shapefile.each { |shape| ... }
yields all shapes in the shapefile.
Equivalent to the following code:
while shape =
--- shapefile.field_count
returns the number of attribute fields made on the DBF file.
--- shapefile.field_decimals field
returns the width of the ((<attribute field>)).
Zero is returned for non-Float fields.
--- shapefile.field_index name
returns the index of the attribute field matching ((|name|)), or nil on failure.
--- shapefile.field_name index
returns the name of the attribute field with ((|index|)), or nil on failure.
--- shapefile.field_type field
returns the type of the ((<attribute field>)).
The result is Symbol
(one of :String, :Integer, :Float, :Logical, or :Invalid)
or nil on failure.
--- shapefile.field_width field
returns the width of the ((<attribute field>)).
--- shapefile.fields
returns an Array containing a list of attribute field name.
--- shapefile.maxbound
returns the maximum values for x, y, m, z coordinates.
Note: the order is M then Z, not Z then M.
--- shapefile.minbound
returns the minimum values for x, y, m, z coordinates.
--- rec = -1
reads the shape/record ((|rec|)) from shapefile.
If ((|rec|)) is missing,
the next record to previously read one
(or the first record #0 for the first time) is used.
An instance of ((<class Shape>)) is returned,
including all attributes written on the DBF.
On error (({nil})) is returned.
--- shapefile.rewind
After that, ((<| rec = -1>))
without argument will return the first shape/record of the shapefile.
--- shapefile.shape_type
returns the type of shape by Symbol.
--- shapefile.size
returns the number of records (or shapes) in the shapefile.
((-If DBF file has different number of records,
warning message is shown in $VERBOSE mode.-))
--- shapefile.write shape, rec = nil
writes ((|shape|)) into shapefile at record number ((|rec|)).
The ((|shape|)) must be a instance of ((<class Shape>)) or subclass.
Attributes attached to ((|shape|)) are stored into DBF file.
If ((|rec|)) is missing, the record is appended at the end of shapefile.
--- shapefile.close
The (({close})) method flushes all information
into the shapefile and release related resources.
After that the instance cannot be used.
It is recommended to call it at the end of processing
to reduce the risk of trouble,
although it is called automatically
at the time of garbage collecting or at the end of interpreter.
== class Shape
Shape consists of a geometric shape (written in SHP file)
and attributes attached to the shape (written in DBF file).
Instance of these subclasses are obtained from
((<ShapeFile#read| rec = -1>))
or constructor like ((<Point::new|class Point>)).
Every instance of the class Shape belongs to one of subclasses,
depending on the type of shape.
=== structure of subclasses
* ((<class Shape>))
* ((<class Point>))
* ((<class PointM>))
* ((<class PointZ>))
* ((<class Arc>))
* ((<class ArcM>))
* ((<class ArcZ>))
* ((<class Polygon>))
* ((<class PolygonM>))
* ((<class PolygonZ>))
* ((<class MultiPoint>))
* ((<class MultiPointM>))
* ((<class MultiPointZ>))
* ((<class MultiPatch>))
=== class method
--- Shape::new hash
Argument ((|hash|)) is a hash (or ((<something behaves like a hash>)))
that contains the attributes of the shape.
Hash returned by ((<shape.to_h>)) can be used as ((|hash|)).
=== instance methods
--- shape [field]
value of the ((<attribute|attribute field>)) ((|field|))
related to the shape.
--- shape [field] = value
sets ((<attribute|attribute field>)) ((|field|)) to ((|value|)).
--- shape.inspect
currently similar to ((<shape.to_h>))(({.to_s})).
--- shape.maxbound
returns the maximum values for x, y, m, z coordinates.
Note: the order is M then Z, not Z then M.
--- shape.minbound
returns the minimum values for x, y, m, z coordinates.
--- shape.part_start
returns an array of Integer that indicates beginning offset
for each part in ((<shape.xvals>)) etc.
--- shape.part_type
returns an array containing ((<part type>)) by Symbol.
Point or multipoint returns (({nil})).
--- shape.rewind_polygon
"This function will reverse any rings necessary
in order to enforce the shapefile restrictions
on the required order of inner and outer rings
in the Shapefile specification.
It returns (({true})) if a change is made and
(({false})) if no change is made.
Only polygon objects will be affected though any object may be passed."
((-taken from ((<ShapeLib>)) document.-))
--- shape.shape_id
returns the number of record by which the shape is read from a shapefile.
Nil is returned if the shape is not read from file.
--- shape.shape_type
returns the ((<type of shape|type of shapes>)) by Symbol.
--- shape.to_h
returns a hash that contains all attributes and geometry information.
Each attribute have a key of String,
while geometry information has keys of Symbol.
pt = ShapeLib::Point::new(1, 2, 'name' => 'Madison')
pt.to_h => {"name"=>"Madison", :zvals=>[0.0], :n_parts=>0,
:n_vertices=>1, :maxbound=>[1.0, 2.0, 0.0, 0.0],
:part_start=>nil, :part_type=>nil, :xvals=>[1.0],
:minbound=>[1.0, 2.0, 0.0, 0.0], :shape_type=>:Point,
:yvals=>[2.0], :mvals=>[0.0], :shape_id=>nil}
--- shape.to_s
current implementation is identical to ((<shape.wkt>)).
Note that this lose information.
--- shape.wkt
returns WKT (well known text) representation of geometry
as defined in ((<ISO 19125-1>)).
((*Caution: current implementation does not always handle Polygon[MZ] and MultiPatch correctly.*))[1, 2], [3, 4], [5, 6]).wkt
=> "LINESTRING(1 2, 3 4, 5 6)"[[1, 2], [3, 4]], [[5, 6], [7, 8]]).wkt
=> "MULTILINESTRING((1 2, 3 4), (5 6, 7 8))"
--- shape.xvals
returns an array of x values.[1, 2], [3, 4], [5, 6]).xvals
=> [1.0, 3.0, 5.0]
Multipart shape results flattened array (all parts joined).[[1, 2], [3, 4]], [[5, 6], [7, 8]]).xvals
=> [1.0, 3.0, 5.0, 7.0]
--- shape.yvals
returns an array of y values.[1, 2], [3, 4], [5, 6]).xvals
=> [2.0, 4.0, 6.0]
--- shape.mvals
returns an array of m values. Nil is returned for missing value.[1, 2], [3, 4], [5, 6]).mvals
=> [nil, nil, nil][1, 2, 3], [4, 5, 6], [7, 8, 9]).mvals
=> [3, 6, 9]
--- shape.zvals
returns an array of z values.
== class Point
Point is a geometric point that has two coordinates x and y.
--- Point::new x, y, attrs = {}
creates a new point instance with coordinates ((|x|)) and ((|y|))
(both are converted to Float).
Optional argument ((|attrs|)) is a hash containing attributes
such as (({{"key1"=>value1, "key2"=>value2, ...}})).
--- point.x
returns a Float x value.
--- point.y
returns a Float y value.
--- point.m
returns a Float m (height) value.
--- point.z
returns a Float z (elevation) value.
== class PointM
Point is a geometric point that has three coordinates x, y and m.
--- PointM::new x, y, m, attrs = {}
== class PointZ
Point is a geometric point that has four coordinates x, y, m and z.
--- PointZ::new x, y, m, z, attrs = {}
== class Arc
Arc is consists of a set of (two or more) points.
Each point has two coordinates x and y.
It is also called polyline.
--- Arc::new point, point, ...
Constructs a single arc.
((|point|)) is array of numerals, or ((<class Point>)).
--- Arc::new [point, point, ...], [point, point, ...], ...
Constructs a multipart arc that represents two disconnected polyline.
== class ArcM
ArcM is similar to Arc, but points also have m (measure) coordinates.
== class ArcZ
ArcZ is similar to ArcM, but points also have z coordinates.
== class Polygon
Polygon is one (or more) closed arc.
--- Polygon::new point, point, ...
Constructs a object with single polygon.
--- Polygon::new [point, point, ...], [point, point, ...], ...
Constructs a object with multiple polygons.
== class PolygonM
PolygonM is similar to Polygon, but points also have m (measure) coordinates.
== class PolygonZ
PolygonZ is similar to PolygonM, but points also have z coordinates.
== class MultiPoint
MultiPoint is a set of points.
--- MultiPoint::new point, point, ...
--- MultiPoint::new [point, point, ...]
Above two are the same.
== class MultiPointM
MultiPointM is similar to MultiPoint, but points also have m (measure) coordinates.
== class MultiPointZ
MultiPointZ is similar to MultiPointM, but points also have z coordinates.
== class MultiPatch
--- MultiPatch::new [part_type, point, point, ...], [part_type, point, ...], ...
Constructs a MultiPatch object.
Note that the first element of each array must be ((<part type>)).
== constants
=== Field Type Constants
--- ShapeLib::String
--- ShapeLib::Integer
--- ShapeLib::Float
== Appendix A: C to Ruby equivalence table
* DBFHandle:
((<class ShapeFile>)) contains DBFHandle.
* SHPHandle:
((<class ShapeFile>)) contains SHPHandle.
* SHPObject:
((<class Shape>)) contains SHPObject and attributes stored in DBF.
Access to members of the structure can be translated using ((<shape.to_h>)).
* SHPOpen():
called in ((<ShapeFile::open|ShapeFile::open filename, access = 'rb'>))
* SHPGetInfo():
((<shapefile.minbound>)), and
* SHPReadObject():
((<| rec = -1>))
* SHPClose():
* SHPCreate():
called in ((<ShapeFile::new|ShapeFile::new filename, shapetype, attrs>))
* SHPCreateSimpleObject() and SHPCreateObject():
((<Shape::new|Shape::new hash>)) and (({new})) method of its subclasses
* SHPComputeExtents():
there is no need to call it, since the current version of
ruby-shapelib does not allow users to change geometry of a shape
once it is created.
* SHPWriteObject():
((<shapefile.write|shapefile.write shape, rec = nil>))
* SHPDestroyObject():
called automatically while the ruby interpreter does garbage collection.
* SHPRewindObject():
* DBFOpen():
called in ((<ShapeFile::open|ShapeFile::open filename, access = 'rb'>))
* DBFCreate():
called in ((<ShapeFile::new|ShapeFile::new filename, shapetype, attrs>))
* DBFGetFieldCount():
* DBFGetRecordCount():
There is no need to call it if shapefile is properly created,
i.e. *.SHP and *.DBF files have the same number of records.
See also ((<shapefile.size>)).
* DBFGetFieldIndex():
((<shapefile.field_index|shapefile.field_index name>))
* DBFGetFieldInfo():
((<shapefile.field_decimals|shapefile.field_decimals field>)),
((<shapefile.field_name|shapefile.field_name index>)),
((<shapefile.field_type|shapefile.field_type field>)), and
((<shapefile.field_width|shapefile.field_width field>))
* DBFAddField():
((<shapefile.add_field|shapefile.add_field field_name, field_type, width, decimal = 0>))
* DBFReadIntegerAttribute(), DBFReadDoubleAttribute(), and
((<shape [field]>))
* DBFIsAttributeNULL():
called in ((<shape [field]>)).
Nil is returned if the attribute is null.
* DBFWriteIntegerAttribute(), DBFWriteDoubleAttribute(), and
((<shape [field] = value>))
* DBFWriteNULLAttribute():
called if (({nil})) is given to ((<shape [field] = value>)).
* DBFGetNativeFieldType():
not implemented in ruby-shapelib.
Does anyone know how to interpret the return value properly?
== Appendix B: Flexible argument
Some method arguments take various objects for convenience.
This appendix discusses the detail of acceptable value.
: should be Float
Any object that respond to (({to_f})) is converted to Float.
String is not acceptable.
(({nil})) is treated as -2e-38 (NODATA) for ((|m|)) (measure) coordinate,
or as 0.0 otherwise.
: type of shapes
For ((<ShapeFile::new|ShapeFile::new filename, shapetype, attrs>))
and ((<Shape::new|Shape::new hash>)),
acceptable values for ((|shapetype|)) are:
* Class object like ShapeLib::Point (listed in ((<structure of subclasses>)))
* String such as (({"Point"})) or (({"PolygonZ"}))
(the same list, but do not include "ShapeLib::")
* Symbol such as (({:Point})) or (({:PolygonZ}))
(result of ((<shapefile.shape_type>)) and ((<shape.shape_type>))),
* Integer code
(please see ((<ESRI Whitepaper>)))
: field type
For ((<shapefile.add_field|shapefile.add_field field_name, field_type, width, decimal = 0>)),
acceptable values for ((|field_type|)) are:
* String "String", "Integer", or "Float", or
* Symbol :String, :Integer, or :Float
(result of ((<shapefile.field_type|shapefile.field_type field>))).
* Integer constants listed ((<above|Field Type Constants>)).
: part type
acceptable values are
* String "TriangleStrip", "TriangleFan", "OuterRing", "InnerRing",
"FirstRing", or "Ring"
* corresponding Symbol :TriangleStrip etc.
: attribute field
For many shapefile methods like ((<shapefile.field_type field>)),
both String name and Integer index are acceptable.
: something behaves like a hash
For ((<Shape::new hash>)), the argument ((|hash|))
* must respond to [((|key|))] method with a Symbol as a ((|key|))
* should respond to (({to_a})) method, so that attributes be loaded
== References
: ShapeLib
: ESRI Whitepaper
or ((<URL:>))
: ISO 19125-1
((<Found on|URL:>)).
Something went wrong with that request. Please try again.