shapelib 0.7.0

Sign up to get free protection for your applications and to get access to all the features.
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>