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

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI02-CSML/trunk/services/3rdParty/Quadtree-0.1.2/shapelib/shp_api.html@2194
Revision 2194, 12.8 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>.SHP File API</title>
4</head>
5<body>
6
7<h1>.SHP File API</h1>
8
9The .SHP API uses a SHPHandle to represent an open .shp/.shx file pair.
10The contents of the SHPHandle are visible (see shapefile.h) but should
11be ignored by the application.  It is intended that all information be
12accessed by the API functions.  <p>
13
14<!-------------------------------------------------------------------------->
15
16<h2>Shape Types</h2>
17
18Shapes have types associated with them.  The following is a list of the
19different shapetypes supported by Shapefiles.  At this time all shapes in
20a Shapefile must be of the same type (with the exception of NULL shapes). <p>
21
22<pre>
23  #define SHPT_NULL             0
24
25  2D Shape Types (pre ArcView 3.x):
26
27  #define SHPT_POINT            1       Points
28  #define SHPT_ARC              3       Arcs (Polylines, possible in parts)
29  #define SHPT_POLYGON          5       Polygons (possible in parts)
30  #define SHPT_MULTIPOINT       8       MultiPoint (related points)
31
32  3D Shape Types (may include "measure" values for vertices):
33
34  #define SHPT_POINTZ           11     
35  #define SHPT_ARCZ             13
36  #define SHPT_POLYGONZ         15
37  #define SHPT_MULTIPOINTZ      18
38
39  2D + Measure Types:
40
41  #define SHPT_POINTM           21
42  #define SHPT_ARCM             23
43  #define SHPT_POLYGONM         25
44  #define SHPT_MULTIPOINTM      28
45
46  Complex (TIN-like) with Z, and Measure:
47
48  #define SHPT_MULTIPATCH       31
49</pre>
50
51<!-------------------------------------------------------------------------->
52
53<h2>SHPObject</h2>
54
55An individual shape is represented by the SHPObject structure.  SHPObject's
56created with SHPCreateObject(), SHPCreateSimpleObject(), or SHPReadObject()
57should be disposed of with SHPDestroyObject().<p>
58
59<pre>
60  typedef struct
61  {
62    int         nSHPType;       Shape Type (SHPT_* - see list above)
63
64    int         nShapeId;       Shape Number (-1 is unknown/unassigned)
65
66    int         nParts;         # of Parts (0 implies single part with no info)
67    int         *panPartStart;  Start Vertex of part
68    int         *panPartType;   Part Type (SHPP_RING if not SHPT_MULTIPATCH)
69   
70    int         nVertices;      Vertex list
71    double      *padfX;         
72    double      *padfY;
73    double      *padfZ;         (all zero if not provided)
74    double      *padfM;         (all zero if not provided)
75
76    double      dfXMin;         Bounds in X, Y, Z and M dimensions
77    double      dfYMin;
78    double      dfZMin;
79    double      dfMMin;
80
81    double      dfXMax;
82    double      dfYMax;
83    double      dfZMax;
84    double      dfMMax;
85  } SHPObject;
86</pre>
87
88<!-------------------------------------------------------------------------->
89
90<h2>SHPOpen()</h2>
91
92<pre>
93SHPHandle SHPOpen( const char * pszShapeFile, const char * pszAccess );
94
95  pszShapeFile:         The name of the layer to access.  This can be the
96                        name of either the .shp or the .shx file or can
97                        just be the path plus the basename of the pair.
98
99  pszAccess:            The fopen() style access string.  At this time only
100                        "rb" (read-only binary) and "rb+" (read/write binary)
101                        should be used.
102</pre>
103
104  The SHPOpen() function should be used to establish access to the two files
105  for accessing vertices (.shp and .shx).  Note that both files have to
106  be in the indicated directory, and must have the expected extensions in
107  lower case.  The returned SHPHandle is passed to other access functions,
108  and SHPClose() should be invoked to recover resources, and flush changes
109  to disk when complete.<p>
110
111<!-------------------------------------------------------------------------->
112
113<h2>SHPGetInfo()</h2>
114
115<pre>
116void SHPGetInfo( SHPHandle hSHP, int * pnEntities, int * pnShapeType,
117                 double * padfMinBound, double * padfMaxBound );
118
119  hSHP:                 The handle previously returned by SHPOpen()
120                        or SHPCreate().
121
122  pnEntities:           A pointer to an integer into which the number of
123                        entities/structures should be placed.  May be NULL.
124
125  pnShapetype:          A pointer to an integer into which the shapetype
126                        of this file should be placed.  Shapefiles may contain
127                        either SHPT_POINT, SHPT_ARC, SHPT_POLYGON or
128                        SHPT_MULTIPOINT entities.  This may be NULL.
129
130  padfMinBound:         The X, Y, Z and M minimum values will be placed into
131                        this four entry array.  This may be NULL.
132                       
133  padfMaxBound:         The X, Y, Z and M maximum values will be placed into
134                        this four entry array.  This may be NULL.
135</pre>
136
137 The SHPGetInfo() function retrieves various information about shapefile
138 as a whole.  The bounds are read from the file header, and may be
139 inaccurate if the file was improperly generated. <p>
140                       
141<!-------------------------------------------------------------------------->
142
143<h2>SHPReadObject()</h2>
144
145<pre>
146SHPObject *SHPReadObject( SHPHandle hSHP, int iShape );
147
148  hSHP:                 The handle previously returned by SHPOpen()
149                        or SHPCreate().
150
151  iShape:               The entity number of the shape to read.  Entity
152                        numbers are between 0 and nEntities-1 (as returned
153                        by SHPGetInfo()).
154</pre>
155
156  The SHPReadObject() call is used to read a single structure, or entity
157  from the shapefile.  See the definition of the SHPObject structure for
158  detailed information on fields of a SHPObject.  SHPObject's returned from
159  SHPReadObject() should be deallocated with SHPDestroyShape(). 
160  SHPReadObject() will return NULL if an illegal iShape value is requested.<p>
161
162  Note that the bounds placed into the SHPObject are those read from the
163  file, and may not be correct.   For points the bounds are generated from
164  the single point since bounds aren't normally provided for point types.<p>
165
166  Generally the shapes returned will be of the type of the file as a whole.
167  However, any file may also contain type SHPT_NULL shapes which will have
168  no geometry.  Generally speaking applications should skip rather than
169  preserve them, as they usually represented interactively deleted shapes.<p>
170
171<!-------------------------------------------------------------------------->
172
173<h2>SHPClose()</h2>
174
175<pre>
176void    SHPClose( SHPHandle hSHP );
177
178  hSHP:                 The handle previously returned by SHPOpen()
179                        or SHPCreate().
180</pre>
181
182  The SHPClose() function will close the .shp and .shx files, and flush
183  all outstanding header information to the files.  It will also recover
184  resources associated with the handle.  After this call the hSHP handle
185  cannot be used again.<p>
186
187<!-------------------------------------------------------------------------->
188
189<h2>SHPCreate()</h2>
190
191<pre>
192SHPHandle SHPCreate( const char * pszShapeFile, int nShapeType );
193
194  pszShapeFile:         The name of the layer to access.  This can be the
195                        name of either the .shp or the .shx file or can
196                        just be the path plus the basename of the pair.
197
198  nShapeType:           The type of shapes to be stored in the newly created
199                        file.  It may be either SHPT_POINT, SHPT_ARC,
200                        SHPT_POLYGON or SHPT_MULTIPOINT.
201</pre>
202
203  The SHPCreate() function will create a new .shp and .shx file of the
204  desired type.<p>
205
206<!-------------------------------------------------------------------------->
207
208<h2>SHPCreateSimpleObject()</h2>
209
210<pre>
211SHPObject *
212     SHPCreateSimpleObject( int nSHPType, int nVertices,
213                            double *padfX, double * padfY, double *padfZ, );
214
215  nSHPType:             The SHPT_ type of the object to be created, such
216                        as SHPT_POINT, or SHPT_POLYGON.
217 
218  nVertices:            The number of vertices being passed in padfX,   
219                        padfY, and padfZ.
220
221  padfX:                An array of nVertices X coordinates of the vertices
222                        for this object.
223
224  padfY:                An array of nVertices Y coordinates of the vertices
225                        for this object.
226
227  padfZ:                An array of nVertices Z coordinates of the vertices
228                        for this object.  This may be NULL in which case
229                        they are all assumed to be zero.
230</pre>
231
232  The SHPCreateSimpleObject() allows for the convenient creation of
233  simple objects.  This is normally used so that the SHPObject can be
234  passed to SHPWriteObject() to write it to the file.  The simple object
235  creation API assumes an M (measure) value of zero for each vertex.  For
236  complex objects (such as polygons) it is assumed that there is only one
237  part, and that it is of the default type (SHPP_RING). <p>
238
239  Use the SHPCreateObject() function for more sophisticated objects.  The
240  SHPDestroyObject() function should be used to free resources associated with
241  an object allocated with SHPCreateSimpleObject(). <p>
242
243  This function computes a bounding box for the SHPObject from the given
244  vertices.<p>
245
246<!-------------------------------------------------------------------------->
247
248<h2>SHPCreateObject()</h2>
249
250<pre>
251SHPObject *
252     SHPCreateObject( int nSHPType, int iShape,
253                      int nParts, int * panPartStart, int * panPartType,
254                      int nVertices, double *padfX, double * padfY,
255                      double *padfZ, double *padfM );
256
257  nSHPType:             The SHPT_ type of the object to be created, such
258                        as SHPT_POINT, or SHPT_POLYGON.
259
260  iShape:               The shapeid to be recorded with this shape.
261
262  nParts:               The number of parts for this object.  If this is
263                        zero for ARC, or POLYGON type objects, a single
264                        zero valued part will be created internally.
265 
266  panPartStart:         The list of zero based start vertices for the rings
267                        (parts) in this object.  The first should always be
268                        zero.  This may be NULL if nParts is 0.
269 
270  panPartType:          The type of each of the parts.  This is only meaningful
271                        for MULTIPATCH files.  For all other cases this may
272                        be NULL, and will be assumed to be SHPP_RING.
273 
274  nVertices:            The number of vertices being passed in padfX,   
275                        padfY, and padfZ.
276
277  padfX:                An array of nVertices X coordinates of the vertices
278                        for this object.
279
280  padfY:                An array of nVertices Y coordinates of the vertices
281                        for this object.
282
283  padfZ:                An array of nVertices Z coordinates of the vertices
284                        for this object.  This may be NULL in which case
285                        they are all assumed to be zero.
286
287  padfM:                An array of nVertices M (measure values) of the
288                        vertices for this object.  This may be NULL in which
289                        case they are all assumed to be zero.
290</pre>
291
292  The SHPCreateSimpleObject() allows for the creation of objects (shapes). 
293  This is normally used so that the SHPObject can be passed to
294  SHPWriteObject() to write it to the file. <p>
295
296  The SHPDestroyObject() function should be used to free resources associated
297  with an object allocated with SHPCreateObject(). <p>
298
299  This function computes a bounding box for the SHPObject from the given
300  vertices.<p>
301
302<!-------------------------------------------------------------------------->
303
304<h2>SHPComputeExtents()</h2>
305
306<pre>
307void SHPComputeExtents( SHPObject * psObject );
308
309  psObject:             An existing shape object to be updated in place.
310</pre>
311 
312  This function will recompute the extents of this shape, replacing the
313  existing values of the dfXMin, dfYMin, dfZMin, dfMMin, dfXMax, dfYMax,
314  dfZMax, and dfMMax values based on the current set of vertices for the
315  shape.   This function is automatically called by SHPCreateObject() but
316  if the vertices of an existing object are altered it should be called again
317  to fix up the extents.<p>
318
319<!-------------------------------------------------------------------------->
320
321<h2>SHPWriteObject()</h2>
322
323<pre>
324int SHPWriteObject( SHPHandle hSHP, int iShape, SHPObject *psObject );
325
326  hSHP:                 The handle previously returned by SHPOpen("r+")
327                        or SHPCreate().
328
329  iShape:               The entity number of the shape to write.  A value of
330                        -1 should be used for new shapes. 
331
332  psObject:             The shape to write to the file. This should have
333                        been created with SHPCreateObject(), or
334                        SHPCreateSimpleObject().
335</pre>
336
337  The SHPWriteObject() call is used to write a single structure, or entity
338  to the shapefile.  See the definition of the SHPObject structure for
339  detailed information on fields of a SHPObject.  The return value is the
340  entity number of the written shape. <p>
341
342<!-------------------------------------------------------------------------->
343
344<h2>SHPDestroyObject()</h2>
345
346<pre>
347void SHPDestroyObject( SHPObject *psObject );
348
349  psObject:             The object to deallocate.
350</pre>
351
352  This function should be used to deallocate the resources associated with
353  a SHPObject when it is no longer needed, including those created with
354  SHPCreateSimpleObject(), SHPCreateObject() and returned from SHPReadObject().
355  <p>
356
357<!-------------------------------------------------------------------------->
358
359<h2>SHPRewindObject()</h2>
360
361<pre>
362int SHPRewindObject( SHPHandle hSHP, SHPObject *psObject );
363
364  hSHP:                 The shapefile (not used at this time).
365  psObject:             The object to deallocate.
366</pre>
367
368  This function will reverse any rings necessary in order to enforce the
369  shapefile restrictions on the required order of inner and outer rings in
370  the Shapefile specification.  It returns TRUE if a change is made and FALSE
371  if no change is made.  Only polygon objects will be affected though any   
372  object may be passed.
373  <p>
374
375</body>
376</html>
Note: See TracBrowser for help on using the repository browser.