source: TI02-CSML/trunk/services/3rdParty/Quadtree-0.1.2/shapelib/shapelib.html @ 2194

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI02-CSML/trunk/services/3rdParty/Quadtree-0.1.2/shapelib/shapelib.html@2194
Revision 2194, 13.1 KB checked in by lawrence, 13 years ago (diff)

Adding various specs and 3rd party code of interest for the CSML
services development.

Line 
1<html>
2<head>
3<title>Shapefile C Library V1.2</title>
4</head>
5
6<body>
7<h1>Shapefile C Library V1.2</h1>
8
9<h2>Purpose</h2>
10
11The Shapefile C Library provides the ability to write simple C programs
12for reading, writing and updating (to a limited extent) ESRI Shapefiles,
13and the associated attribute file (.dbf).<p>
14
15<h2>Manifest</h2>
16
17<ul>
18<li> <b>shapelib.html</b>: This file - general documentation on the
19Shapefile C Library.<p>
20
21<li> <b><a href="shp_api.html">shp_api.html</a></b>: Documentation
22for the API for accessing the .shp/.shx files. <p>
23
24<li> <b><a href="dbf_api.html">dbf_api.html</a></b>: Documentation
25for the API for accessing the .dbf attribute files. <p>
26
27<li> <b>shpopen.c</b>: C code for access to .shp/.shx vertex files.<p>
28
29<li> <b>dbfopen.c</b>: C code for access to .dbf attribute file.<p>
30
31<li> <b>shapefil.h</b>:  Include file defining all the services of dbfopen.c
32and shpopen.c.<p>
33
34<li> <b>contrib/</b>: A directory of "in progress" contributed programs
35from Carl Anderson.<p>
36
37<li> <b>dbfcreate.c</b>: Simple example program for creating a new .dbf file.
38     <p>
39
40<li> <b>dbfadd.c</b>:
41        Simple example program for adding a record to a .dbf file.<p>
42
43<li> <b>dbfdump.c</b>: Simple example program for displaying the contents of
44                  a .dbf file.<p>
45
46<li> <b>shpcreate.c</b>: Simple example program for creating a new .shp and
47.shx file.<p>
48
49<li> <b>shpadd.c</b>: Simple example program for adding a shape to an existing
50                  shape file.<p>
51
52<li> <b>shpdump.c</b>: Simple program for dumping all the vertices in a
53                shapefile with an indicating of the parts.<p>
54
55<li> <b>shputils.c</b>: Complex contributed program capable of clipping and
56                  appending
57                  shapefiles as well as a few other things.  Type shputils
58                  after building to get a full usage message.<p>
59
60<li> <b>Makefile</b>: A simple makefile to compile the library and example
61                  programs.<p>
62
63<li> <b>makeshape.sh</b>: A simple script for running some of the example
64programs.<p>
65
66<li> <b>shptest.c</b>: A simple test harnass to generate each of the supported
67                  types of shapefiles. <p>
68
69
70<li> <b>shptree.c</b>: Implements a simple quadtree algorithm for fast
71spatial searches of shapefiles.<p>
72
73<li> <b>shptreedump.c</b>: A simple mainly showing information on quad
74trees build using the quad tree api.<p>
75
76<li> <b>stream1.sh</b> - A test script, which should produce stream1.out. 
77Note this will only work if you have the example data downloaded.<p>
78
79<li> <b>stream1.out</b>: Expected output of stream1.sh test script.<p>
80
81<li> <b>stream2.sh</b>: A test script, which should produce stream2.out.<p>
82
83<li> <b>stream2.out</b>: Expected output of stream2.sh test script.<p>
84
85<li> <b>pyshapelib-0.1</b>: Prototype contributed Python bindings.<p>
86
87</ul>
88
89<h2>What is a Shapefile?</h2>
90
91If you don't know, you probably don't need this library.  The Shapefile
92format is a new working and interchange format promulagated by ESRI
93(http://www.esri.com/) for simple vector data with attributes.  It is
94apparently the only file format that can be edited in ARCView 2/3, and can
95also be exported and imported in Arc/Info.  <p>
96
97An excellent white paper on the shapefile format is available from ESRI,
98but it is .pdf format, so you will need Adobe Acrobat to browse it.<p>
99
100The file format actually consists of three files.<p>
101
102<pre>
103XXX.shp - holds the actual vertices.
104XXX.shx - hold index data pointing to the structures in the .shp file.
105XXX.dbf - holds the attributes in xBase (dBase) format. 
106</pre>
107
108<h2>Release Notes</h2>
109
110To get notification of new releases of Shapelib <i>subscribe</i> to
111the project at www.freshmeat.net.  This is currently the only reliable
112way of finding out about new releases since there is no shapelib specific
113mailing list.<p>
114
115<b>Release 1.2.10</b>: Added SHPRewindObject() function, and shprewind utility
116program.  Added FTLogical, DBFReadLogicalAttribute() and
117DBFWriteLogicalAttribute() (thanks to Olek Neyman). <p>
118
119<b>Release 1.2.9</b>: Good support for reading and writing NULL fields
120in .dbf files, good support for NULL shapes and addition of the
121DBFGetFieldIndex() functions (all contributed by Jim Matthews).<p>
122
123An upgraded shputils.c has been contributed by Bill Miller.  Daniel
124Morissette contributed DBFGetNativeFieldType().  Better error checking
125for disk errors in dbfopen.c.  Various other bug fixes and safety improvements.
126<p>
127
128<b>Release 1.2.8</b>: Added hacked libtool support (supplied by Jan)
129and "rpm ready" install logic.<p>
130
131<b>Release 1.2.7</b>: Fix record size (was 4 bytes too long).  Modify
132SHPReadObject() to handle null shapes properly.  Use atof() instead of
133sscanf().  Support .DBF as well as .dbf.<p>
134
135<b>Release 1.2.6</b>: Now available under old MIT style license, or at the
136users option, LGPL.  Added the contrib directory of stuff from Carl Anderson
137and the shptree.c API for quadtree based spatial searches.<p>
138
139<b>Release 1.2.5</b>: SHPOpen() now forcably uses "rb" or "r+b" access string
140to avoid common mistakes on Windows.  Also fixed a serious bug with .dbf
141files with a 'F' field type.<p>
142
143<b>Release 1.2.4</b>: DBFOpen() will now automatically translate a .shp
144extension to .dbf for convenience.  SHPOpen() will try datasets with lower
145and uppercase extension.  DBFAddField() now returns the field number,
146not TRUE/FALSE.<p>
147
148<b>Release 1.2.3</b>: Disable writing measures to multi-patches as ArcView
149seems to puke on them (as reported by Monika Sester).  Add white space
150trimming, and string/numeric attribute interchangability in DBF API
151as suggested by Steve Lime.  Dbfdump was updated to include several
152reporting options.<p>
153
154<b>Release 1.2.2</b>: Added proper support for multipatch (reading and
155writing) - this release just for testing purposes.<p>
156
157<b>Release 1.2</b> is mostly a rewrite of the .shp/.shx access API to account
158for ArcView 3.x 3D shapes, and to encapsulate the shapes in a structure. 
159Existing code using the shapefile library will require substantial changes
160to use release 1.2.<p>
161
162<b>Release V1.1</b> has been built on a number of platforms, and used by a
163number of people successfully.  V1.1 is the first release with the xBase API
164documentation.<p>
165
166
167<h2>Maintainer</h2>
168
169This library is maintained by me (Frank Warmerdam) on my own time.  Please
170send me bug patches and suggestions for the library.  Email can be sent to
171warmerdam@pobox.com.<p>
172
173The current status of the Shapelib code can be found at
174<a href="http://pobox.com/~warmerdam/root/projects/shapelib/">
175http://pobox.com/~warmerdam/root/projects/shapelib/</a>.  To find out about
176new releases of Shapelib, select the "Subscribe to new releases" option
177from the link at
178<a href="http://freshmeat.net/projects/shapelib/">Freshmeat</a>.<p>
179
180The shputils.c module was contributed by Bill Miller (NC-DOT) who can be
181reached at bmiller@doh.dot.state.nc.us.  I had to modify it substantially
182to work with the 1.2 API, and I am not sure that it works as well as it
183did when it was originally provided by Bill.<p>
184
185<h2>Credits</h2>
186
187I didn't start this section anywhere near soon enough, so alot of earlier
188contributors to Shapelib are lost in pre-history.
189
190<ul>
191<li> Bill Miller (NY-DOT) for shputils.c
192<li> Carl Anderson for the contents of the contrib directory, and
193the "tuple" additions to dbfopen.c.
194<li> Andrea Giacomelli for patches for dbfopen.c.
195<li> Doug Matthews for portability improvements.
196<li> Jan-Oliver Wagner for convincing me to make it available under LGPL,
197shared library support, and various other patches.
198<li> Dennis Christopher (of Avenza) for testing and bug fixes.
199<li> Miko Syrjä (of 3D-system Oy) for a record size bug fix.
200<li> Steven Lime and Curtis Hill for help with NULL shapes.
201<li> Jim Matthews for support of NULL attributes in dbf files.
202<li> <a href="http://www.pcigeomatics.com/">PCI Geomatics</a> who let me
203release a modified version of their shapefile code in the beginning and
204who hosted shapelib for years.
205</ul>
206
207<h2>In Memorium</h2>
208
209I would like to dedicate Shapelib to the memory of Sol Katz.  While I never
210met him in person, his generous contributions to the GIS community took
211many forms, including free distribution of a variety of GIS translators
212with source.  The fact that he used this Shapelib in some of his utilities,
213and thanked me was a great encouragement to me.  I hope I can do his memory
214honour by trying to contribute in a similar fashion.<p>
215
216<h2>Portability</h2>
217
218The Shapefile C Library should port easily to 32bit systems with ANSI C
219compilers.  It should work on 64 bit architectures (such as the DEC AXP).<p>
220
221Care should also be taken to pass the binary access flag into SHPOpen()
222and DBFOpen() when operating on systems with special text file translation
223such as MSDOS.<p>
224
225The shputils.c module is contributed, and may not take the same approach
226to portability as the rest of the package.<p>
227
228On Linux, and most unix systems it should be possible to build and
229install shapefile support as a shared library using the "lib" and "lib_install"
230targets of the Makefile.  Note that this Makefile doesn't use autoconf
231mechanisms and will generally require some hand tailoring for your environment.
232
233<h2>Limitations</h2>
234
235<ul>
236
237<li> You can't modify the vertices of existing structures (though you
238   can update the attributes of existing structures, and create new
239   structures).<p>
240
241<li> Not written in such a way as to be particularly fast.  This is
242particularly true of the 1.2 API.  For applications more concerned with
243speed it may be worth using the V1.1 API.<p>
244
245<li> Doesn't set the last access time properly in the .dbf files.<p>
246
247<li> There is no way to synchronize information to the file except to close it.
248<p>
249
250<li> Poor error checking and reporting.<p>
251
252<li> Not professionally supported (well it can be, if you want to pay).<p>
253
254<li> Some aspects of xBase files not supported, though I believe they are
255not used by ESRI.<p>
256
257<li> The application must keep the .dbf file in sync with the .shp/.shx
258files through appropriate use of the DBF and SHP APIs.<p>
259
260<li> No support for the undocumented .sbn/.sbx spatial index files.<p>
261
262</ul>
263
264<h2>Copyright</h2>
265
266The source for the Shapefile C Library is (c) 1998 Frank Warmerdam,
267and released under the following conditions.  The intent is that anyone
268can do anything with the code, but that I do not assume any liability, nor
269express any warranty for this code.  <p>
270
271As of Shapelib 1.2.6 the core portions of the library are made available
272under two possible licenses.  The licensee can choose to use the code
273under either the Library GNU Public License (LGPL) described in
274LICENSE.LGPL or under the following MIT style license.  Any files in
275the Shapelib distribution without explicit copyright license terms
276(such as this documentation, the Makefile and so forth) should be
277considered to have the following licensing terms.  Some auxilary portions
278of Shapelib, notably some of the components in the contrib directory
279come under slightly different license restrictions.  Check the source
280files that you are actually using for conditions.<p>
281
282<h3>Default License Terms</h3>
283
284<quote>
285Copyright (c) 1999, Frank Warmerdam<p>
286
287This software is available under the following "MIT Style" license,
288or at the option of the licensee under the LGPL (see LICENSE.LGPL).  This
289option is discussed in more detail in shapelib.html.<p>
290 
291Permission is hereby granted, free of charge, to any person obtaining a
292copy of this software and associated documentation files (the "Software"),
293to deal in the Software without restriction, including without limitation
294the rights to use, copy, modify, merge, publish, distribute, sublicense,
295and/or sell copies of the Software, and to permit persons to whom the
296Software is furnished to do so, subject to the following conditions:<p>
297
298The above copyright notice and this permission notice shall be included
299in all copies or substantial portions of the Software.<p>
300
301THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
302OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
303FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
304THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
305LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
306FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
307DEALINGS IN THE SOFTWARE.<p>
308</quote>
309
310<h3>Shapelib Modifications</h3>
311
312I am pleased to receive bug fixes, and improvements for Shapelib.  Unless
313the submissions indicate otherwise I will assume that changes submitted to
314me remain under the the above "dual license" terms.  If changes are made
315to the library with the intention that those changes should be protected by
316the LGPL then I should be informed upon submission.  Note that I will not
317generally incorporate changes into the core of Shapelib that are protected
318under the LGPL as this would effectively limit the whole file and
319distribution to LGPL terms.<p>
320
321<h3>Opting for LGPL</h3>
322
323For licensee's opting to use Shapelib under LGPL as opposed to the MIT
324Style license above, and wishing to redistribute the software based on
325Shapelib, I would ask that all "dual license" modules be updated to
326indicate that only the LGPL (and not the MIT Style license) applies.  This
327action represents opting for the LGPL, and thereafter LGPL terms apply to
328any redistribution and modification of the affected modules.<p>
329
330</body>
331</html>
332
333
334
Note: See TracBrowser for help on using the repository browser.