/usr/share/doc/shapelib/shapelib.html

<html>
<head>
<title>Shapefile C Library V1.2</title>
</head>

<body>
<h1>Shapefile C Library V1.2</h1>

<h2>Purpose</h2>

The Shapefile C Library provides the ability to write simple C programs
for reading, writing and updating (to a limited extent) ESRI Shapefiles,
and the associated attribute file (.dbf).<p>

<h2>Manifest</h2>

<ul>
<li> <b>shapelib.html</b>: This file - general documentation on the 
Shapefile C Library.<p>

<li> <b><a href="shp_api.html">shp_api.html</a></b>: Documentation 
for the API for accessing the .shp/.shx files. <p>

<li> <b><a href="dbf_api.html">dbf_api.html</a></b>: Documentation 
for the API for accessing the .dbf attribute files. <p>

<li> <b>shpopen.c</b>: C code for access to .shp/.shx vertex files.<p>

<li> <b>dbfopen.c</b>: C code for access to .dbf attribute file.<p>

<li> <b>shapefil.h</b>:  Include file defining all the services of dbfopen.c 
and shpopen.c.<p>

<li> <b>contrib/</b>: A directory of "in progress" contributed programs
from Carl Anderson.<p>

<li> <b>dbfcreate.c</b>: Simple example program for creating a new .dbf file.
     <p>

<li> <b>dbfadd.c</b>: 
	Simple example program for adding a record to a .dbf file.<p>

<li> <b>dbfdump.c</b>: Simple example program for displaying the contents of
		  a .dbf file.<p>

<li> <b>shpcreate.c</b>: Simple example program for creating a new .shp and 
.shx file.<p>

<li> <b>shpadd.c</b>: Simple example program for adding a shape to an existing
		  shape file.<p>

<li> <b>shpdump.c</b>: Simple program for dumping all the vertices in a 
		shapefile with an indicating of the parts.<p>

<li> <b>shputils.c</b>: Complex contributed program capable of clipping and 
		  appending
                  shapefiles as well as a few other things.  Type shputils
                  after building to get a full usage message.<p>

<li> <b>Makefile</b>: A simple makefile to compile the library and example 
		  programs.<p>

<li> <b>makeshape.sh</b>: A simple script for running some of the example 
programs.<p>

<li> <b>shptest.c</b>: A simple test harnass to generate each of the supported
		  types of shapefiles. <p>


<li> <b>shptree.c</b>: Implements a simple quadtree algorithm for fast
spatial searches of shapefiles.<p>

<li> <b>shptreedump.c</b>: A simple mainly showing information on quad
trees build using the quad tree api.<p>

<li> <b>stream1.sh</b> - A test script, which should produce stream1.out.  
Note this will only work if you have the example data downloaded.<p>

<li> <b>stream1.out</b>: Expected output of stream1.sh test script.<p>

<li> <b>stream2.sh</b>: A test script, which should produce stream2.out.<p>

<li> <b>stream2.out</b>: Expected output of stream2.sh test script.<p>

<li> <b>pyshapelib-0.1</b>: Prototype contributed Python bindings.<p>

</ul>

<h2>What is a Shapefile?</h2>

If you don't know, you probably don't need this library.  The Shapefile
format is a new working and interchange format promulagated by ESRI 
(http://www.esri.com/) for simple vector data with attributes.  It is
apparently the only file format that can be edited in ARCView 2/3, and can
also be exported and imported in Arc/Info.  <p>

An excellent white paper on the shapefile format is available from ESRI,
but it is .pdf format, so you will need Adobe Acrobat to browse it.<p>

The file format actually consists of three files.<p>

<pre>
XXX.shp - holds the actual vertices.
XXX.shx - hold index data pointing to the structures in the .shp file.
XXX.dbf - holds the attributes in xBase (dBase) format.  
</pre>

<h2>Release Notes</h2>

To get notification of new releases of Shapelib <i>subscribe</i> to 
the project at www.freshmeat.net.  This is currently the only reliable
way of finding out about new releases since there is no shapelib specific
mailing list.<p>

<b>Release 1.2.10</b>: Added SHPRewindObject() function, and shprewind utility
program.  Added FTLogical, DBFReadLogicalAttribute() and 
DBFWriteLogicalAttribute() (thanks to Olek Neyman). <p>

<b>Release 1.2.9</b>: Good support for reading and writing NULL fields 
in .dbf files, good support for NULL shapes and addition of the
DBFGetFieldIndex() functions (all contributed by Jim Matthews).<p>

An upgraded shputils.c has been contributed by Bill Miller.  Daniel 
Morissette contributed DBFGetNativeFieldType().  Better error checking
for disk errors in dbfopen.c.  Various other bug fixes and safety improvements.
<p>

<b>Release 1.2.8</b>: Added hacked libtool support (supplied by Jan)
and "rpm ready" install logic.<p>

<b>Release 1.2.7</b>: Fix record size (was 4 bytes too long).  Modify 
SHPReadObject() to handle null shapes properly.  Use atof() instead of
sscanf().  Support .DBF as well as .dbf.<p>

<b>Release 1.2.6</b>: Now available under old MIT style license, or at the
users option, LGPL.  Added the contrib directory of stuff from Carl Anderson
and the shptree.c API for quadtree based spatial searches.<p>

<b>Release 1.2.5</b>: SHPOpen() now forcably uses "rb" or "r+b" access string
to avoid common mistakes on Windows.  Also fixed a serious bug with .dbf
files with a 'F' field type.<p>

<b>Release 1.2.4</b>: DBFOpen() will now automatically translate a .shp
extension to .dbf for convenience.  SHPOpen() will try datasets with lower
and uppercase extension.  DBFAddField() now returns the field number,
not TRUE/FALSE.<p>

<b>Release 1.2.3</b>: Disable writing measures to multi-patches as ArcView
seems to puke on them (as reported by Monika Sester).  Add white space 
trimming, and string/numeric attribute interchangability in DBF API
as suggested by Steve Lime.  Dbfdump was updated to include several 
reporting options.<p>

<b>Release 1.2.2</b>: Added proper support for multipatch (reading and 
writing) - this release just for testing purposes.<p>

<b>Release 1.2</b> is mostly a rewrite of the .shp/.shx access API to account 
for ArcView 3.x 3D shapes, and to encapsulate the shapes in a structure.  
Existing code using the shapefile library will require substantial changes
to use release 1.2.<p>

<b>Release V1.1</b> has been built on a number of platforms, and used by a 
number of people successfully.  V1.1 is the first release with the xBase API 
documentation.<p>


<h2>Maintainer</h2>

This library is maintained by me (Frank Warmerdam) on my own time.  Please 
send me bug patches and suggestions for the library.  Email can be sent to 
warmerdam@pobox.com.<p>

The current status of the Shapelib code can be found at
<a href="http://pobox.com/~warmerdam/root/projects/shapelib/">
http://pobox.com/~warmerdam/root/projects/shapelib/</a>.  To find out about 
new releases of Shapelib, select the "Subscribe to new releases" option 
from the link at 
<a href="http://freshmeat.net/projects/shapelib/">Freshmeat</a>.<p>

The shputils.c module was contributed by Bill Miller (NC-DOT) who can be
reached at bmiller@doh.dot.state.nc.us.  I had to modify it substantially
to work with the 1.2 API, and I am not sure that it works as well as it
did when it was originally provided by Bill.<p>

<h2>Credits</h2>

I didn't start this section anywhere near soon enough, so alot of earlier
contributors to Shapelib are lost in pre-history.

<ul>
<li> Bill Miller (NY-DOT) for shputils.c
<li> Carl Anderson for the contents of the contrib directory, and 
the "tuple" additions to dbfopen.c.
<li> Andrea Giacomelli for patches for dbfopen.c.
<li> Doug Matthews for portability improvements.
<li> Jan-Oliver Wagner for convincing me to make it available under LGPL,
shared library support, and various other patches.
<li> Dennis Christopher (of Avenza) for testing and bug fixes.
<li> Miko Syrjä (of 3D-system Oy) for a record size bug fix.
<li> Steven Lime and Curtis Hill for help with NULL shapes.
<li> Jim Matthews for support of NULL attributes in dbf files.
<li> <a href="http://www.pcigeomatics.com/">PCI Geomatics</a> who let me
release a modified version of their shapefile code in the beginning and
who hosted shapelib for years.
</ul>

<h2>In Memorium</h2>

I would like to dedicate Shapelib to the memory of Sol Katz.  While I never
met him in person, his generous contributions to the GIS community took 
many forms, including free distribution of a variety of GIS translators
with source.  The fact that he used this Shapelib in some of his utilities, 
and thanked me was a great encouragement to me.  I hope I can do his memory 
honour by trying to contribute in a similar fashion.<p>

<h2>Portability</h2>

The Shapefile C Library should port easily to 32bit systems with ANSI C
compilers.  It should work on 64 bit architectures (such as the DEC AXP).<p>

Care should also be taken to pass the binary access flag into SHPOpen()
and DBFOpen() when operating on systems with special text file translation
such as MSDOS.<p>

The shputils.c module is contributed, and may not take the same approach
to portability as the rest of the package.<p>

On Linux, and most unix systems it should be possible to build and 
install shapefile support as a shared library using the "lib" and "lib_install"
targets of the Makefile.  Note that this Makefile doesn't use autoconf
mechanisms and will generally require some hand tailoring for your environment.

<h2>Limitations</h2>

<ul>

<li> You can't modify the vertices of existing structures (though you 
   can update the attributes of existing structures, and create new 
   structures).<p>

<li> Not written in such a way as to be particularly fast.  This is 
particularly true of the 1.2 API.  For applications more concerned with
speed it may be worth using the V1.1 API.<p>

<li> Doesn't set the last access time properly in the .dbf files.<p>

<li> There is no way to synchronize information to the file except to close it.
<p>

<li> Poor error checking and reporting.<p>

<li> Not professionally supported (well it can be, if you want to pay).<p>

<li> Some aspects of xBase files not supported, though I believe they are
not used by ESRI.<p>

<li> The application must keep the .dbf file in sync with the .shp/.shx
files through appropriate use of the DBF and SHP APIs.<p>

<li> No support for the undocumented .sbn/.sbx spatial index files.<p>

</ul>

<h2>Copyright</h2>

The source for the Shapefile C Library is (c) 1998 Frank Warmerdam, 
and released under the following conditions.  The intent is that anyone
can do anything with the code, but that I do not assume any liability, nor
express any warranty for this code.  <p>

As of Shapelib 1.2.6 the core portions of the library are made available
under two possible licenses.  The licensee can choose to use the code
under either the Library GNU Public License (LGPL) described in 
LICENSE.LGPL or under the following MIT style license.  Any files in
the Shapelib distribution without explicit copyright license terms
(such as this documentation, the Makefile and so forth) should be
considered to have the following licensing terms.  Some auxilary portions
of Shapelib, notably some of the components in the contrib directory
come under slightly different license restrictions.  Check the source
files that you are actually using for conditions.<p>

<h3>Default License Terms</h3>

<quote>
Copyright (c) 1999, Frank Warmerdam<p>

This software is available under the following "MIT Style" license,
or at the option of the licensee under the LGPL (see LICENSE.LGPL).  This
option is discussed in more detail in shapelib.html.<p>
 
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:<p>

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.<p>

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.<p>
</quote>

<h3>Shapelib Modifications</h3>

I am pleased to receive bug fixes, and improvements for Shapelib.  Unless
the submissions indicate otherwise I will assume that changes submitted to
me remain under the the above "dual license" terms.  If changes are made
to the library with the intention that those changes should be protected by
the LGPL then I should be informed upon submission.  Note that I will not
generally incorporate changes into the core of Shapelib that are protected 
under the LGPL as this would effectively limit the whole file and 
distribution to LGPL terms.<p>

<h3>Opting for LGPL</h3>

For licensee's opting to use Shapelib under LGPL as opposed to the MIT
Style license above, and wishing to redistribute the software based on 
Shapelib, I would ask that all "dual license" modules be updated to
indicate that only the LGPL (and not the MIT Style license) applies.  This
action represents opting for the LGPL, and thereafter LGPL terms apply to
any redistribution and modification of the affected modules.<p>

</body>
</html>
shapelib 1.2.10-7 / usr / share / doc / shapelib / shapelib.html
