shapelib 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. data/README.md +59 -0
  2. data/Rakefile +47 -0
  3. data/doc/Interface.html +558 -0
  4. data/doc/Interface.rd +498 -0
  5. data/doc/style.css +136 -0
  6. data/ext/shapelib_ext/depend +49 -0
  7. data/ext/shapelib_ext/extconf.rb +19 -0
  8. data/ext/shapelib_ext/main.c +102 -0
  9. data/ext/shapelib_ext/sfcode.h +284 -0
  10. data/ext/shapelib_ext/sflist.h +21 -0
  11. data/ext/shapelib_ext/shpplus.c +588 -0
  12. data/ext/shapelib_ext/shpplus.h +86 -0
  13. data/ext/shapelib_ext/spcode.h +704 -0
  14. data/ext/shapelib_ext/splist.h +71 -0
  15. data/ext/shapelib_ext/spwkt.h +219 -0
  16. data/ext/shapelib_ext/valconv.h +313 -0
  17. data/lib/shapelib.rb +2 -0
  18. data/lib/shapelib/shape.rb +14 -0
  19. data/lib/shapelib/version.rb +3 -0
  20. data/test/libtest.rb +80 -0
  21. data/test/zsample1.rb +168 -0
  22. data/test/ztest1.rb +253 -0
  23. metadata +103 -0
data/README.md ADDED
@@ -0,0 +1,59 @@
1
+ Shapelib bindings for Ruby
2
+ ===============================
3
+
4
+ This is a wrapper module of Shapefile C Library for Ruby. Originally authored by
5
+ prasinos@users.sourceforge.net.
6
+
7
+ How to install
8
+ -----------------
9
+
10
+ * You must have ShapeLib and ruby.
11
+ * It is expected to run on all ruby-running environments. But it is tested
12
+ only on RedHat Enterprise Linux 4.0 and Vine Linux 3.0.
13
+
14
+ OSX
15
+ ----------------
16
+
17
+ Install MacPorts. Use it to install the shapelib C library:
18
+
19
+ sudo port install shapelib
20
+
21
+ Now install the gem, pointing it to the port installation:
22
+
23
+ gem build shapelib.gemspec
24
+ gem install shapelib-X.X.X.gem -- --with-opt-dir=/opt/local
25
+
26
+ Quick directions
27
+ ----------------
28
+
29
+ $ tar xvfz ruby-shapelib.tar.gz (you did it if you see this file)
30
+ $ cd ruby-shapelib
31
+ $ ruby ./extconf.rb
32
+ $ make
33
+ # make install
34
+
35
+
36
+ Troubleshooting
37
+ ---------------
38
+
39
+ * I have ruby but can't run extconf.rb
40
+
41
+ Some Linux distributions divide Ruby into several packages such as
42
+ "ruby" and "ruby-devel". You may have to install additional packages.
43
+
44
+ * I have shapelib installed but extconf.rb fails
45
+
46
+ Try --with-shapelib-include= and --with-shapelib-lib= options of extconf.rb.
47
+
48
+ If above advice doesn't help, please visit
49
+ http://sourceforge.net/projects/ruby-shapelib and post a message.
50
+
51
+ How to use
52
+ ==========
53
+
54
+ Please see doc/Interface.html.
55
+
56
+ License issues
57
+ ==============
58
+
59
+ Ruby-ShapeLib is provided under LGPL or ShapeLib's MIT-style default license.
data/Rakefile ADDED
@@ -0,0 +1,47 @@
1
+ require 'rubygems'
2
+ require 'rake'
3
+ require 'jeweler'
4
+ $LOAD_PATH << File.expand_path('lib')
5
+
6
+ begin
7
+ require 'shapelib/version'
8
+ Jeweler::Tasks.new do |gem|
9
+ gem.name = "shapelib"
10
+ gem.summary = %Q{Simple wrapper around the shapelib library}
11
+ gem.description = gem.summary
12
+ gem.email = %q{mmangino@elevatedrails.com}
13
+ gem.homepage = "http://github.com/mperham/shapelib"
14
+ gem.authors = ["prasinos@users.sourceforge.net", "Mike Mangino", "Mike Perham"]
15
+ gem.add_development_dependency 'rake-compiler', '>= 0.7.0'
16
+ gem.has_rdoc = false
17
+ gem.version = Shapelib::VERSION
18
+ # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
19
+ end
20
+ Jeweler::GemcutterTasks.new
21
+ rescue LoadError => le
22
+ puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler: #{le.message}"
23
+ end
24
+
25
+ require 'rake/testtask'
26
+ Rake::TestTask.new(:test) do |test|
27
+ test.libs = %w(lib test)
28
+ test.pattern = 'test/**/test_*.rb'
29
+ test.verbose = true
30
+ end
31
+
32
+ task :test => :check_dependencies
33
+ task :default => :test
34
+
35
+ require 'rake/rdoctask'
36
+ Rake::RDocTask.new do |rdoc|
37
+ rdoc.rdoc_dir = 'rdoc'
38
+ rdoc.title = "shapelib"
39
+ rdoc.rdoc_files.include('README*')
40
+ rdoc.rdoc_files.include('lib/**/*.rb')
41
+ end
42
+
43
+
44
+ gem 'rake-compiler', '>= 0.7.0'
45
+ require "rake/extensiontask"
46
+
47
+ Rake::ExtensionTask.new('shapelib_ext')
data/doc/Interface.html ADDED
@@ -0,0 +1,558 @@
1
+ <?xml version="1.0" ?>
2
+ <!DOCTYPE html
3
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
+ <html xmlns="http://www.w3.org/1999/xhtml">
6
+ <head>
7
+ <title>ruby-shapelib API</title>
8
+ <link href="style.css" type="text/css" rel="stylesheet" />
9
+ </head>
10
+ <body>
11
+ <h1><a name="label-0" id="label-0">module ShapeLib</a></h1><!-- RDLabel: "module ShapeLib" -->
12
+ <p>This module is a wrapper of C Shapefile Library
13
+ (also called <a href="http://shapelib.maptools.org/">ShapeLib</a>).
14
+ It consists of basically two classes:
15
+ <a href="#label-5">ShapeFile</a> and <a href="#label-29">Shape</a>.
16
+ If you are unfamiliar with object-oriented programming,
17
+ please see <a href="#label-83">Appendix A: C to Ruby equivalence table</a>.</p>
18
+ <p>A extension library <code>shapelib</code> must be required before using this module:</p>
19
+ <pre>require 'shapelib'</pre>
20
+ <h2><a name="label-1" id="label-1">module functions</a></h2><!-- RDLabel: "module functions" -->
21
+ <p>Following three functions construct a point object.
22
+ It can be used like top level function after <code>include</code>:</p>
23
+ <pre>include ShapeLib
24
+ pt = new_point(1, 2)</pre>
25
+ <p>Arguments <var>x</var>, <var>y</var>, <var>z</var>, and <var>m</var> <a href="#label-85">should be Float</a>.</p>
26
+ <dl>
27
+ <dt><a name="label-2" id="label-2"><code>ShapeLib.new_point <var>x</var>, <var>y</var></code></a></dt><!-- RDLabel: "ShapeLib.new_point x, y" -->
28
+ <dd>
29
+ creates a <a href="#label-51">class Point</a> object.</dd>
30
+ <dt><a name="label-3" id="label-3"><code>ShapeLib.new_point <var>x</var>, <var>y</var>, <var>m</var></code></a></dt><!-- RDLabel: "ShapeLib.new_point x, y, m" -->
31
+ <dd>
32
+ creates a <a href="#label-57">class PointM</a> object.</dd>
33
+ <dt><a name="label-4" id="label-4"><code>ShapeLib.new_point <var>x</var>, <var>y</var>, <var>m</var>, <var>z</var></code></a></dt><!-- RDLabel: "ShapeLib.new_point x, y, m, z" -->
34
+ <dd>
35
+ creates a <a href="#label-59">class PointZ</a> object.</dd>
36
+ </dl>
37
+ <h2><a name="label-5" id="label-5">class ShapeFile</a></h2><!-- RDLabel: "class ShapeFile" -->
38
+ <h3><a name="label-6" id="label-6">class methods</a></h3><!-- RDLabel: "class methods" -->
39
+ <p>Following two class methods <code>new</code> and <code>open</code>
40
+ return an instance of <a href="#label-5">class ShapeFile</a> if succeeded.
41
+ Exception is raised on failure.
42
+ It is recommended to call <a href="#label-28">shapefile.close</a>
43
+ when each shapefile is no longer used.</p>
44
+ <dl>
45
+ <dt><a name="label-7" id="label-7"><code>ShapeFile::open <var>filename</var>, <var>access</var> = '<var>rb</var>'</code></a></dt><!-- RDLabel: "ShapeFile::open filename, access = 'rb'" -->
46
+ <dt><a name="label-8" id="label-8"><code>ShapeFile::open(<var>filename</var>, <var>access</var> = '<var>rb</var>') { |<var>fp</var>| ... }</code></a></dt><!-- RDLabel: "ShapeFile::open" -->
47
+ <dd>
48
+ <p>The <code>open</code> method opens an existing shapefile. </p>
49
+ <p>Argument <var>filename</var> should be
50
+ either fullname (like "<code>basename.shp</code>")
51
+ or just basename (like "<code>basename</code>").
52
+ Suffix <code>.shp</code> must be lowercase if specified.
53
+ Both <code>.shp</code> and <code>.shx</code> files must exist at the specified path.</p>
54
+ <p>Argument <var>access</var> are passed to <code>fopen(3)</code> through
55
+ <a href="#label-92">ShapeLib</a> <code>SHPOpen()</code> function.
56
+ Either '<code>rb</code>' or '<code>rb+</code>' should be used.</p>
57
+ <p>If a block is given to these constructors,
58
+ the opened shapefile object is yielded like File::open.
59
+ The shapefile is closed at the end of block,
60
+ and the constructor returns <code>nil</code>.</p>
61
+ <pre># example
62
+ ShapeLib::ShapeFile.open(filename) { |fp|
63
+ print "#{filename} has #{fp.size} records.\n"
64
+ }</pre></dd>
65
+ <dt><a name="label-9" id="label-9"><code>ShapeFile::new <var>filename</var>, <var>shapetype</var>, <var>attrs</var></code></a></dt><!-- RDLabel: "ShapeFile::new filename, shapetype, attrs" -->
66
+ <dt><a name="label-10" id="label-10"><code>ShapeFile::new(<var>filename</var>, <var>shapetype</var>, <var>attrs</var>) { |<var>fp</var>| ... }</code></a></dt><!-- RDLabel: "ShapeFile::new" -->
67
+ <dd>
68
+ <p>The <code>new</code> method creates a shapefile.
69
+ All three files (<code>.shp</code>, <code>.shx</code>, and <code>.dbf</code>) are created.
70
+ Argument <var>shapetype</var> specifies the <a href="#label-86">type of shapes</a>
71
+ to be stored in the shapefile.
72
+ Argument <var>attrs</var> is an array of arrays
73
+ that specifies <var>field_name</var>, <var>field_type</var>, <var>width</var>,
74
+ and optional <var>decimal</var> as in
75
+ <a href="#label-12">shapefile.add_field</a>
76
+ .</p>
77
+ <pre># example
78
+ fp = ShapeFile::new('city.shp', :Point,
79
+ [['name', :String, 32],
80
+ ['population', :Integer, 9],
81
+ ['height', :Float, 9, 1]])</pre></dd>
82
+ </dl>
83
+ <h3><a name="label-11" id="label-11">instance methods</a></h3><!-- RDLabel: "instance methods" -->
84
+ <dl>
85
+ <dt><a name="label-12" id="label-12"><code>shapefile.add_field <var>field_name</var>, <var>field_type</var>, <var>width</var>, <var>decimal</var> = <var>0</var></code></a></dt><!-- RDLabel: "shapefile.add_field field_name, field_type, width, decimal = 0" -->
86
+ <dd>
87
+ <p>Adds an attribute field to the shapefile (that must be newly created by
88
+ <a href="#label-9">ShapeFile::new</a>).
89
+ Argument <var>field_name</var> is a String for field name;
90
+ <var>field_type</var> specifies <a href="#label-87">field type</a>;
91
+ <var>width</var> is nonnegative Integer for field width in characters; and
92
+ <var>decimal</var> is nonnegative Integer for decimal points.
93
+ Only Float field requires <var>decimal</var>; otherwise it can be missing.</p>
94
+ <pre># example
95
+ fp.add_field 'name', :String, 32
96
+ fp.add_field 'height', "Float", 9, 1</pre></dd>
97
+ <dt><a name="label-13" id="label-13"><code>shapefile.each { |<var>shape</var>| ... }</code></a></dt><!-- RDLabel: "shapefile.each" -->
98
+ <dd>
99
+ <p>yields all shapes in the shapefile.
100
+ Equivalent to the following code:</p>
101
+ <pre>shapefile.rewind
102
+ while shape = shapefile.read
103
+ ...
104
+ end</pre></dd>
105
+ <dt><a name="label-14" id="label-14"><code>shapefile.field_count</code></a></dt><!-- RDLabel: "shapefile.field_count" -->
106
+ <dd>
107
+ returns the number of attribute fields made on the DBF file.</dd>
108
+ <dt><a name="label-15" id="label-15"><code>shapefile.field_decimals <var>field</var></code></a></dt><!-- RDLabel: "shapefile.field_decimals field" -->
109
+ <dd>
110
+ returns the width of the <a href="#label-89">attribute field</a>.
111
+ Zero is returned for non-Float fields.</dd>
112
+ <dt><a name="label-16" id="label-16"><code>shapefile.field_index <var>name</var></code></a></dt><!-- RDLabel: "shapefile.field_index name" -->
113
+ <dd>
114
+ returns the index of the attribute field matching <var>name</var>, or nil on failure.</dd>
115
+ <dt><a name="label-17" id="label-17"><code>shapefile.field_name <var>index</var></code></a></dt><!-- RDLabel: "shapefile.field_name index" -->
116
+ <dd>
117
+ returns the name of the attribute field with <var>index</var>, or nil on failure.</dd>
118
+ <dt><a name="label-18" id="label-18"><code>shapefile.field_type <var>field</var></code></a></dt><!-- RDLabel: "shapefile.field_type field" -->
119
+ <dd>
120
+ returns the type of the <a href="#label-89">attribute field</a>.
121
+ The result is Symbol
122
+ (one of :String, :Integer, :Float, :Logical, or :Invalid)
123
+ or nil on failure.</dd>
124
+ <dt><a name="label-19" id="label-19"><code>shapefile.field_width <var>field</var></code></a></dt><!-- RDLabel: "shapefile.field_width field" -->
125
+ <dd>
126
+ returns the width of the <a href="#label-89">attribute field</a>.</dd>
127
+ <dt><a name="label-20" id="label-20"><code>shapefile.fields</code></a></dt><!-- RDLabel: "shapefile.fields" -->
128
+ <dd>
129
+ returns an Array containing a list of attribute field name.</dd>
130
+ <dt><a name="label-21" id="label-21"><code>shapefile.maxbound</code></a></dt><!-- RDLabel: "shapefile.maxbound" -->
131
+ <dd>
132
+ returns the maximum values for x, y, m, z coordinates.
133
+ Note: the order is M then Z, not Z then M.</dd>
134
+ <dt><a name="label-22" id="label-22"><code>shapefile.minbound</code></a></dt><!-- RDLabel: "shapefile.minbound" -->
135
+ <dd>
136
+ returns the minimum values for x, y, m, z coordinates.</dd>
137
+ <dt><a name="label-23" id="label-23"><code>shapefile.read <var>rec</var> = -<var>1</var></code></a></dt><!-- RDLabel: "shapefile.read rec = -1" -->
138
+ <dd>
139
+ reads the shape/record <var>rec</var> from shapefile.
140
+ If <var>rec</var> is missing,
141
+ the next record to previously read one
142
+ (or the first record #0 for the first time) is used.
143
+ An instance of <a href="#label-29">class Shape</a> is returned,
144
+ including all attributes written on the DBF.
145
+ On error <code>nil</code> is returned.</dd>
146
+ <dt><a name="label-24" id="label-24"><code>shapefile.rewind</code></a></dt><!-- RDLabel: "shapefile.rewind" -->
147
+ <dd>
148
+ After that, <a href="#label-23">shapefile.read</a>
149
+ without argument will return the first shape/record of the shapefile.</dd>
150
+ <dt><a name="label-25" id="label-25"><code>shapefile.shape_type</code></a></dt><!-- RDLabel: "shapefile.shape_type" -->
151
+ <dd>
152
+ returns the type of shape by Symbol.</dd>
153
+ <dt><a name="label-26" id="label-26"><code>shapefile.size</code></a></dt><!-- RDLabel: "shapefile.size" -->
154
+ <dd>
155
+ returns the number of records (or shapes) in the shapefile.
156
+ <a name="footmark-1" id="footmark-1" href="#foottext-1"><sup><small>*1</small></sup></a></dd>
157
+ <dt><a name="label-27" id="label-27"><code>shapefile.write <var>shape</var>, <var>rec</var> = <var>nil</var></code></a></dt><!-- RDLabel: "shapefile.write shape, rec = nil" -->
158
+ <dd>
159
+ writes <var>shape</var> into shapefile at record number <var>rec</var>.
160
+ The <var>shape</var> must be a instance of <a href="#label-29">class Shape</a> or subclass.
161
+ Attributes attached to <var>shape</var> are stored into DBF file.
162
+ If <var>rec</var> is missing, the record is appended at the end of shapefile.</dd>
163
+ <dt><a name="label-28" id="label-28"><code>shapefile.close</code></a></dt><!-- RDLabel: "shapefile.close" -->
164
+ <dd>
165
+ <p>The <code>close</code> method flushes all information
166
+ into the shapefile and release related resources.
167
+ After that the instance cannot be used.</p>
168
+ <p>It is recommended to call it at the end of processing
169
+ to reduce the risk of trouble,
170
+ although it is called automatically
171
+ at the time of garbage collecting or at the end of interpreter.</p></dd>
172
+ </dl>
173
+ <h2><a name="label-29" id="label-29">class Shape</a></h2><!-- RDLabel: "class Shape" -->
174
+ <p>Shape consists of a geometric shape (written in SHP file)
175
+ and attributes attached to the shape (written in DBF file).
176
+ Instance of these subclasses are obtained from
177
+ <a href="#label-23">ShapeFile#read</a>
178
+ or constructor like <a href="#label-51">Point::new</a>.</p>
179
+ <p>Every instance of the class Shape belongs to one of subclasses,
180
+ depending on the type of shape. </p>
181
+ <h3><a name="label-30" id="label-30">structure of subclasses</a></h3><!-- RDLabel: "structure of subclasses" -->
182
+ <ul>
183
+ <li><a href="#label-29">class Shape</a>
184
+ <ul>
185
+ <li><a href="#label-51">class Point</a>
186
+ <ul>
187
+ <li><a href="#label-57">class PointM</a>
188
+ <ul>
189
+ <li><a href="#label-59">class PointZ</a></li>
190
+ </ul></li>
191
+ </ul></li>
192
+ <li><a href="#label-61">class Arc</a>
193
+ <ul>
194
+ <li><a href="#label-64">class ArcM</a>
195
+ <ul>
196
+ <li><a href="#label-65">class ArcZ</a></li>
197
+ </ul></li>
198
+ </ul></li>
199
+ <li><a href="#label-66">class Polygon</a>
200
+ <ul>
201
+ <li><a href="#label-69">class PolygonM</a>
202
+ <ul>
203
+ <li><a href="#label-70">class PolygonZ</a> </li>
204
+ </ul></li>
205
+ </ul></li>
206
+ <li><a href="#label-71">class MultiPoint</a>
207
+ <ul>
208
+ <li><a href="#label-74">class MultiPointM</a>
209
+ <ul>
210
+ <li><a href="#label-75">class MultiPointZ</a> </li>
211
+ </ul></li>
212
+ </ul></li>
213
+ <li><a href="#label-76">class MultiPatch</a> </li>
214
+ </ul></li>
215
+ </ul>
216
+ <h3><a name="label-31" id="label-31">class method</a></h3><!-- RDLabel: "class method" -->
217
+ <dl>
218
+ <dt><a name="label-32" id="label-32"><code>Shape::new <var>hash</var></code></a></dt><!-- RDLabel: "Shape::new hash" -->
219
+ <dd>
220
+ Argument <var>hash</var> is a hash (or <a href="#label-90">something behaves like a hash</a>)
221
+ that contains the attributes of the shape.
222
+ Hash returned by <a href="#label-44">shape.to_h</a> can be used as <var>hash</var>.</dd>
223
+ </dl>
224
+ <h3><a name="label-33" id="label-33">instance methods</a></h3><!-- RDLabel: "instance methods" -->
225
+ <dl>
226
+ <dt><a name="label-34" id="label-34"><code>shape [<var>field</var>]</code></a></dt><!-- RDLabel: "shape [field]" -->
227
+ <dd>
228
+ value of the <a href="#label-89">attribute</a> <var>field</var>
229
+ related to the shape.</dd>
230
+ <dt><a name="label-35" id="label-35"><code>shape [<var>field</var>] = <var>value</var></code></a></dt><!-- RDLabel: "shape [field] = value" -->
231
+ <dd>
232
+ sets <a href="#label-89">attribute</a> <var>field</var> to <var>value</var>.</dd>
233
+ <dt><a name="label-36" id="label-36"><code>shape.inspect</code></a></dt><!-- RDLabel: "shape.inspect" -->
234
+ <dd>
235
+ currently similar to <a href="#label-44">shape.to_h</a><code>.to_s</code>.</dd>
236
+ <dt><a name="label-37" id="label-37"><code>shape.maxbound</code></a></dt><!-- RDLabel: "shape.maxbound" -->
237
+ <dd>
238
+ returns the maximum values for x, y, m, z coordinates.
239
+ Note: the order is M then Z, not Z then M.</dd>
240
+ <dt><a name="label-38" id="label-38"><code>shape.minbound</code></a></dt><!-- RDLabel: "shape.minbound" -->
241
+ <dd>
242
+ returns the minimum values for x, y, m, z coordinates.</dd>
243
+ <dt><a name="label-39" id="label-39"><code>shape.part_start</code></a></dt><!-- RDLabel: "shape.part_start" -->
244
+ <dd>
245
+ returns an array of Integer that indicates beginning offset
246
+ for each part in <a href="#label-47">shape.xvals</a> etc.</dd>
247
+ <dt><a name="label-40" id="label-40"><code>shape.part_type</code></a></dt><!-- RDLabel: "shape.part_type" -->
248
+ <dd>
249
+ returns an array containing <a href="#label-88">part type</a> by Symbol.
250
+ Point or multipoint returns <code>nil</code>.</dd>
251
+ <dt><a name="label-41" id="label-41"><code>shape.rewind_polygon</code></a></dt><!-- RDLabel: "shape.rewind_polygon" -->
252
+ <dd>
253
+ "This function will reverse any rings necessary
254
+ in order to enforce the shapefile restrictions
255
+ on the required order of inner and outer rings
256
+ in the Shapefile specification.
257
+ It returns <code>true</code> if a change is made and
258
+ <code>false</code> if no change is made.
259
+ Only polygon objects will be affected though any object may be passed."
260
+ <a name="footmark-2" id="footmark-2" href="#foottext-2"><sup><small>*2</small></sup></a></dd>
261
+ <dt><a name="label-42" id="label-42"><code>shape.shape_id</code></a></dt><!-- RDLabel: "shape.shape_id" -->
262
+ <dd>
263
+ returns the number of record by which the shape is read from a shapefile.
264
+ Nil is returned if the shape is not read from file.</dd>
265
+ <dt><a name="label-43" id="label-43"><code>shape.shape_type</code></a></dt><!-- RDLabel: "shape.shape_type" -->
266
+ <dd>
267
+ returns the <a href="#label-86">type of shape</a> by Symbol.</dd>
268
+ <dt><a name="label-44" id="label-44"><code>shape.to_h</code></a></dt><!-- RDLabel: "shape.to_h" -->
269
+ <dd>
270
+ <p>returns a hash that contains all attributes and geometry information.
271
+ Each attribute have a key of String,
272
+ while geometry information has keys of Symbol.</p>
273
+ <pre>pt = ShapeLib::Point::new(1, 2, 'name' =&gt; 'Madison')
274
+ pt.to_h =&gt; {"name"=&gt;"Madison", :zvals=&gt;[0.0], :n_parts=&gt;0,
275
+ :n_vertices=&gt;1, :maxbound=&gt;[1.0, 2.0, 0.0, 0.0],
276
+ :part_start=&gt;nil, :part_type=&gt;nil, :xvals=&gt;[1.0],
277
+ :minbound=&gt;[1.0, 2.0, 0.0, 0.0], :shape_type=&gt;:Point,
278
+ :yvals=&gt;[2.0], :mvals=&gt;[0.0], :shape_id=&gt;nil}</pre></dd>
279
+ <dt><a name="label-45" id="label-45"><code>shape.to_s</code></a></dt><!-- RDLabel: "shape.to_s" -->
280
+ <dd>
281
+ current implementation is identical to <a href="#label-46">shape.wkt</a>.
282
+ Note that this lose information.</dd>
283
+ <dt><a name="label-46" id="label-46"><code>shape.wkt</code></a></dt><!-- RDLabel: "shape.wkt" -->
284
+ <dd>
285
+ <p>returns WKT (well known text) representation of geometry
286
+ as defined in <a href="#label-94">ISO 19125-1</a>.
287
+ <em>Caution: current implementation does not always handle Polygon[MZ] and MultiPatch correctly.</em></p>
288
+ <pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).wkt
289
+ =&gt; "LINESTRING(1 2, 3 4, 5 6)"
290
+ ShapeLib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).wkt
291
+ =&gt; "MULTILINESTRING((1 2, 3 4), (5 6, 7 8))"</pre></dd>
292
+ <dt><a name="label-47" id="label-47"><code>shape.xvals</code></a></dt><!-- RDLabel: "shape.xvals" -->
293
+ <dd>
294
+ <p>returns an array of x values.</p>
295
+ <pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
296
+ =&gt; [1.0, 3.0, 5.0]</pre>
297
+ <p>Multipart shape results flattened array (all parts joined).</p>
298
+ <pre>ShapeLib::Arc.new([[1, 2], [3, 4]], [[5, 6], [7, 8]]).xvals
299
+ =&gt; [1.0, 3.0, 5.0, 7.0]</pre></dd>
300
+ <dt><a name="label-48" id="label-48"><code>shape.yvals</code></a></dt><!-- RDLabel: "shape.yvals" -->
301
+ <dd>
302
+ <p>returns an array of y values.</p>
303
+ <pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).xvals
304
+ =&gt; [2.0, 4.0, 6.0]</pre></dd>
305
+ <dt><a name="label-49" id="label-49"><code>shape.mvals</code></a></dt><!-- RDLabel: "shape.mvals" -->
306
+ <dd>
307
+ <p>returns an array of m values. Nil is returned for missing value.</p>
308
+ <pre>ShapeLib::Arc.new([1, 2], [3, 4], [5, 6]).mvals
309
+ =&gt; [nil, nil, nil]
310
+ ShapeLib::ArcM.new([1, 2, 3], [4, 5, 6], [7, 8, 9]).mvals
311
+ =&gt; [3, 6, 9]</pre></dd>
312
+ <dt><a name="label-50" id="label-50"><code>shape.zvals</code></a></dt><!-- RDLabel: "shape.zvals" -->
313
+ <dd>
314
+ returns an array of z values.</dd>
315
+ </dl>
316
+ <h2><a name="label-51" id="label-51">class Point</a></h2><!-- RDLabel: "class Point" -->
317
+ <p>Point is a geometric point that has two coordinates x and y.</p>
318
+ <dl>
319
+ <dt><a name="label-52" id="label-52"><code>Point::new <var>x</var>, <var>y</var>, <var>attrs</var> = {}</code></a></dt><!-- RDLabel: "Point::new x, y, attrs =" -->
320
+ <dd>
321
+ creates a new point instance with coordinates <var>x</var> and <var>y</var>
322
+ (both are converted to Float).
323
+ Optional argument <var>attrs</var> is a hash containing attributes
324
+ such as <code>{"key1"=&gt;value1, "key2"=&gt;value2, ...}</code>.</dd>
325
+ <dt><a name="label-53" id="label-53"><code>point.x</code></a></dt><!-- RDLabel: "point.x" -->
326
+ <dd>
327
+ returns a Float x value.</dd>
328
+ <dt><a name="label-54" id="label-54"><code>point.y</code></a></dt><!-- RDLabel: "point.y" -->
329
+ <dd>
330
+ returns a Float y value.</dd>
331
+ <dt><a name="label-55" id="label-55"><code>point.m</code></a></dt><!-- RDLabel: "point.m" -->
332
+ <dd>
333
+ returns a Float m (height) value.</dd>
334
+ <dt><a name="label-56" id="label-56"><code>point.z</code></a></dt><!-- RDLabel: "point.z" -->
335
+ <dd>
336
+ returns a Float z (elevation) value.</dd>
337
+ </dl>
338
+ <h2><a name="label-57" id="label-57">class PointM</a></h2><!-- RDLabel: "class PointM" -->
339
+ <p>Point is a geometric point that has three coordinates x, y and m.</p>
340
+ <dl>
341
+ <dt><a name="label-58" id="label-58"><code>PointM::new <var>x</var>, <var>y</var>, <var>m</var>, <var>attrs</var> = {}</code></a></dt><!-- RDLabel: "PointM::new x, y, m, attrs =" -->
342
+ </dl>
343
+ <h2><a name="label-59" id="label-59">class PointZ</a></h2><!-- RDLabel: "class PointZ" -->
344
+ <p>Point is a geometric point that has four coordinates x, y, m and z.</p>
345
+ <dl>
346
+ <dt><a name="label-60" id="label-60"><code>PointZ::new <var>x</var>, <var>y</var>, <var>m</var>, <var>z</var>, <var>attrs</var> = {}</code></a></dt><!-- RDLabel: "PointZ::new x, y, m, z, attrs =" -->
347
+ </dl>
348
+ <h2><a name="label-61" id="label-61">class Arc</a></h2><!-- RDLabel: "class Arc" -->
349
+ <p>Arc is consists of a set of (two or more) points.
350
+ Each point has two coordinates x and y.
351
+ It is also called polyline.</p>
352
+ <dl>
353
+ <dt><a name="label-62" id="label-62"><code>Arc::new <var>point</var>, <var>point</var>, ...</code></a></dt><!-- RDLabel: "Arc::new point, point, ..." -->
354
+ <dd>
355
+ Constructs a single arc.
356
+ <var>point</var> is array of numerals, or <a href="#label-51">class Point</a>.</dd>
357
+ <dt><a name="label-63" id="label-63"><code>Arc::new [<var>point</var>, <var>point</var>, ...], [<var>point</var>, <var>point</var>, ...], ...</code></a></dt><!-- RDLabel: "Arc::new [point, point, ...], [point, point, ...], ..." -->
358
+ <dd>
359
+ Constructs a multipart arc that represents two disconnected polyline.</dd>
360
+ </dl>
361
+ <h2><a name="label-64" id="label-64">class ArcM</a></h2><!-- RDLabel: "class ArcM" -->
362
+ <p>ArcM is similar to Arc, but points also have m (measure) coordinates.</p>
363
+ <h2><a name="label-65" id="label-65">class ArcZ</a></h2><!-- RDLabel: "class ArcZ" -->
364
+ <p>ArcZ is similar to ArcM, but points also have z coordinates.</p>
365
+ <h2><a name="label-66" id="label-66">class Polygon</a></h2><!-- RDLabel: "class Polygon" -->
366
+ <p>Polygon is one (or more) closed arc.</p>
367
+ <dl>
368
+ <dt><a name="label-67" id="label-67"><code>Polygon::new <var>point</var>, <var>point</var>, ...</code></a></dt><!-- RDLabel: "Polygon::new point, point, ..." -->
369
+ <dd>
370
+ Constructs a object with single polygon.</dd>
371
+ <dt><a name="label-68" id="label-68"><code>Polygon::new [<var>point</var>, <var>point</var>, ...], [<var>point</var>, <var>point</var>, ...], ...</code></a></dt><!-- RDLabel: "Polygon::new [point, point, ...], [point, point, ...], ..." -->
372
+ <dd>
373
+ Constructs a object with multiple polygons.</dd>
374
+ </dl>
375
+ <h2><a name="label-69" id="label-69">class PolygonM</a></h2><!-- RDLabel: "class PolygonM" -->
376
+ <p>PolygonM is similar to Polygon, but points also have m (measure) coordinates.</p>
377
+ <h2><a name="label-70" id="label-70">class PolygonZ</a></h2><!-- RDLabel: "class PolygonZ" -->
378
+ <p>PolygonZ is similar to PolygonM, but points also have z coordinates.</p>
379
+ <h2><a name="label-71" id="label-71">class MultiPoint</a></h2><!-- RDLabel: "class MultiPoint" -->
380
+ <p>MultiPoint is a set of points.</p>
381
+ <dl>
382
+ <dt><a name="label-72" id="label-72"><code>MultiPoint::new <var>point</var>, <var>point</var>, ...</code></a></dt><!-- RDLabel: "MultiPoint::new point, point, ..." -->
383
+ <dt><a name="label-73" id="label-73"><code>MultiPoint::new [<var>point</var>, <var>point</var>, ...]</code></a></dt><!-- RDLabel: "MultiPoint::new [point, point, ...]" -->
384
+ <dd>
385
+ Above two are the same.</dd>
386
+ </dl>
387
+ <h2><a name="label-74" id="label-74">class MultiPointM</a></h2><!-- RDLabel: "class MultiPointM" -->
388
+ <p>MultiPointM is similar to MultiPoint, but points also have m (measure) coordinates.</p>
389
+ <h2><a name="label-75" id="label-75">class MultiPointZ</a></h2><!-- RDLabel: "class MultiPointZ" -->
390
+ <p>MultiPointZ is similar to MultiPointM, but points also have z coordinates.</p>
391
+ <h2><a name="label-76" id="label-76">class MultiPatch</a></h2><!-- RDLabel: "class MultiPatch" -->
392
+ <dl>
393
+ <dt><a name="label-77" id="label-77"><code>MultiPatch::new [<var>part_type</var>, <var>point</var>, <var>point</var>, ...], [<var>part_type</var>, <var>point</var>, ...], ...</code></a></dt><!-- RDLabel: "MultiPatch::new [part_type, point, point, ...], [part_type, point, ...], ..." -->
394
+ <dd>
395
+ Constructs a MultiPatch object.
396
+ Note that the first element of each array must be <a href="#label-88">part type</a>.</dd>
397
+ </dl>
398
+ <h2><a name="label-78" id="label-78">constants</a></h2><!-- RDLabel: "constants" -->
399
+ <h3><a name="label-79" id="label-79">Field Type Constants</a></h3><!-- RDLabel: "Field Type Constants" -->
400
+ <dl>
401
+ <dt><a name="label-80" id="label-80"><code>ShapeLib::String</code></a></dt><!-- RDLabel: "ShapeLib::String" -->
402
+ <dt><a name="label-81" id="label-81"><code>ShapeLib::Integer</code></a></dt><!-- RDLabel: "ShapeLib::Integer" -->
403
+ <dt><a name="label-82" id="label-82"><code>ShapeLib::Float</code></a></dt><!-- RDLabel: "ShapeLib::Float" -->
404
+ </dl>
405
+ <h2><a name="label-83" id="label-83">Appendix A: C to Ruby equivalence table</a></h2><!-- RDLabel: "Appendix A: C to Ruby equivalence table" -->
406
+ <ul>
407
+ <li>DBFHandle:
408
+ <a href="#label-5">class ShapeFile</a> contains DBFHandle.</li>
409
+ <li>SHPHandle:
410
+ <a href="#label-5">class ShapeFile</a> contains SHPHandle.</li>
411
+ <li>SHPObject:
412
+ <a href="#label-29">class Shape</a> contains SHPObject and attributes stored in DBF.
413
+ Access to members of the structure can be translated using <a href="#label-44">shape.to_h</a>.</li>
414
+ <li>SHPOpen():
415
+ called in <a href="#label-7">ShapeFile::open</a></li>
416
+ <li>SHPGetInfo():
417
+ <a href="#label-26">shapefile.size</a>,
418
+ <a href="#label-25">shapefile.shape_type</a>,
419
+ <a href="#label-22">shapefile.minbound</a>, and
420
+ <a href="#label-21">shapefile.maxbound</a>.</li>
421
+ <li>SHPReadObject():
422
+ <a href="#label-23">shapefile.read</a></li>
423
+ <li>SHPClose():
424
+ <a href="#label-28">shapefile.close</a></li>
425
+ <li>SHPCreate():
426
+ called in <a href="#label-9">ShapeFile::new</a></li>
427
+ <li>SHPCreateSimpleObject() and SHPCreateObject():
428
+ <a href="#label-32">Shape::new</a> and <code>new</code> method of its subclasses</li>
429
+ <li>SHPComputeExtents():
430
+ there is no need to call it, since the current version of
431
+ ruby-shapelib does not allow users to change geometry of a shape
432
+ once it is created.</li>
433
+ <li>SHPWriteObject():
434
+ <a href="#label-27">shapefile.write</a></li>
435
+ <li>SHPDestroyObject():
436
+ called automatically while the ruby interpreter does garbage collection.</li>
437
+ <li>SHPRewindObject():
438
+ <a href="#label-41">shape.rewind_polygon</a></li>
439
+ <li>DBFOpen():
440
+ called in <a href="#label-7">ShapeFile::open</a></li>
441
+ <li>DBFCreate():
442
+ called in <a href="#label-9">ShapeFile::new</a></li>
443
+ <li>DBFGetFieldCount():
444
+ <a href="#label-14">shapefile.field_count</a></li>
445
+ <li>DBFGetRecordCount():
446
+ There is no need to call it if shapefile is properly created,
447
+ i.e. *.SHP and *.DBF files have the same number of records.
448
+ See also <a href="#label-26">shapefile.size</a>.</li>
449
+ <li>DBFGetFieldIndex():
450
+ <a href="#label-16">shapefile.field_index</a></li>
451
+ <li>DBFGetFieldInfo():
452
+ <a href="#label-15">shapefile.field_decimals</a>,
453
+ <a href="#label-17">shapefile.field_name</a>,
454
+ <a href="#label-18">shapefile.field_type</a>, and
455
+ <a href="#label-19">shapefile.field_width</a></li>
456
+ <li>DBFAddField():
457
+ <a href="#label-12">shapefile.add_field</a></li>
458
+ <li>DBFReadIntegerAttribute(), DBFReadDoubleAttribute(), and
459
+ DBFReadStringAttribute():
460
+ <a href="#label-34">shape [field]</a></li>
461
+ <li>DBFIsAttributeNULL():
462
+ called in <a href="#label-34">shape [field]</a>.
463
+ Nil is returned if the attribute is null.</li>
464
+ <li>DBFWriteIntegerAttribute(), DBFWriteDoubleAttribute(), and
465
+ DBFWriteStringAttribute():
466
+ <a href="#label-35">shape [field] = value</a></li>
467
+ <li>DBFWriteNULLAttribute():
468
+ called if <code>nil</code> is given to <a href="#label-35">shape [field] = value</a>.</li>
469
+ <li>DBFGetNativeFieldType():
470
+ not implemented in ruby-shapelib.
471
+ Does anyone know how to interpret the return value properly?</li>
472
+ </ul>
473
+ <h2><a name="label-84" id="label-84">Appendix B: Flexible argument</a></h2><!-- RDLabel: "Appendix B: Flexible argument" -->
474
+ <p>Some method arguments take various objects for convenience.
475
+ This appendix discusses the detail of acceptable value.</p>
476
+ <dl>
477
+ <dt><a name="label-85" id="label-85">should be Float</a></dt><!-- RDLabel: "should be Float" -->
478
+ <dd>
479
+ Any object that respond to <code>to_f</code> is converted to Float.
480
+ String is not acceptable.
481
+ <code>nil</code> is treated as -2e-38 (NODATA) for <var>m</var> (measure) coordinate,
482
+ or as 0.0 otherwise.
483
+ </dd>
484
+ <dt><a name="label-86" id="label-86">type of shapes</a></dt><!-- RDLabel: "type of shapes" -->
485
+ <dd>
486
+ For <a href="#label-9">ShapeFile::new</a>
487
+ and <a href="#label-32">Shape::new</a>,
488
+ acceptable values for <var>shapetype</var> are:
489
+ <ul>
490
+ <li>Class object like ShapeLib::Point (listed in <a href="#label-30">structure of subclasses</a>)</li>
491
+ <li>String such as <code>"Point"</code> or <code>"PolygonZ"</code>
492
+ (the same list, but do not include "ShapeLib::")</li>
493
+ <li>Symbol such as <code>:Point</code> or <code>:PolygonZ</code>
494
+ (result of <a href="#label-25">shapefile.shape_type</a> and <a href="#label-43">shape.shape_type</a>),
495
+ or</li>
496
+ <li>Integer code
497
+ (please see <a href="#label-93">ESRI Whitepaper</a>)</li>
498
+ </ul>
499
+ </dd>
500
+ <dt><a name="label-87" id="label-87">field type</a></dt><!-- RDLabel: "field type" -->
501
+ <dd>
502
+ For <a href="#label-12">shapefile.add_field</a>,
503
+ acceptable values for <var>field_type</var> are:
504
+ <ul>
505
+ <li>String "String", "Integer", or "Float", or</li>
506
+ <li>Symbol :String, :Integer, or :Float
507
+ (result of <a href="#label-18">shapefile.field_type</a>).</li>
508
+ <li>Integer constants listed <a href="#label-79">above</a>.</li>
509
+ </ul>
510
+ </dd>
511
+ <dt><a name="label-88" id="label-88">part type</a></dt><!-- RDLabel: "part type" -->
512
+ <dd>
513
+ acceptable values are
514
+ <ul>
515
+ <li>String "TriangleStrip", "TriangleFan", "OuterRing", "InnerRing",
516
+ "FirstRing", or "Ring"</li>
517
+ <li>corresponding Symbol :TriangleStrip etc.</li>
518
+ </ul>
519
+ </dd>
520
+ <dt><a name="label-89" id="label-89">attribute field</a></dt><!-- RDLabel: "attribute field" -->
521
+ <dd>
522
+ For many shapefile methods like <a href="#label-18">shapefile.field_type field</a>,
523
+ both String name and Integer index are acceptable.
524
+ </dd>
525
+ <dt><a name="label-90" id="label-90">something behaves like a hash</a></dt><!-- RDLabel: "something behaves like a hash" -->
526
+ <dd>
527
+ For <a href="#label-32">Shape::new hash</a>, the argument <var>hash</var>
528
+ <ul>
529
+ <li>must respond to [<var>key</var>] method with a Symbol as a <var>key</var></li>
530
+ <li>should respond to <code>to_a</code> method, so that attributes be loaded </li>
531
+ </ul>
532
+ </dd>
533
+ </dl>
534
+ <h2><a name="label-91" id="label-91">References</a></h2><!-- RDLabel: "References" -->
535
+ <dl>
536
+ <dt><a name="label-92" id="label-92">ShapeLib</a></dt><!-- RDLabel: "ShapeLib" -->
537
+ <dd>
538
+ <a href="http://shapelib.maptools.org/shp_api.html">&lt;URL:http://shapelib.maptools.org/shp_api.html&gt;</a>
539
+ <a href="http://shapelib.maptools.org/dbf_api.html">&lt;URL:http://shapelib.maptools.org/dbf_api.html&gt;</a>
540
+ </dd>
541
+ <dt><a name="label-93" id="label-93">ESRI Whitepaper</a></dt><!-- RDLabel: "ESRI Whitepaper" -->
542
+ <dd>
543
+ <a href="http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf">&lt;URL:http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf&gt;</a>
544
+ or <a href="http://shapelib.maptools.org/dl/shapefile.pdf">&lt;URL:http://shapelib.maptools.org/dl/shapefile.pdf&gt;</a>
545
+ </dd>
546
+ <dt><a name="label-94" id="label-94">ISO 19125-1</a></dt><!-- RDLabel: "ISO 19125-1" -->
547
+ <dd>
548
+ <a href="http://portal.opengeospatial.org/modules/admin/license_agreement.php?suppressHeaders=0&amp;access_license_id=3&amp;target=http://portal.opengeospatial.org/files/index.php?artifact_id=13227">Found on opengeospatial.org</a>.
549
+ </dd>
550
+ </dl>
551
+ <hr />
552
+ <p class="foottext">
553
+ <a name="foottext-1" id="foottext-1" href="#footmark-1"><sup><small>*1</small></sup></a><small>If DBF file has different number of records,
554
+ warning message is shown in $VERBOSE mode.</small><br />
555
+ <a name="foottext-2" id="foottext-2" href="#footmark-2"><sup><small>*2</small></sup></a><small>taken from <a href="#label-92">ShapeLib</a> document.</small><br />
556
+ </p>
557
+ </body>
558
+ </html>