1 /*
2  gaia_network.h -- Gaia common support for Topology-Network
3 
4  version 5.0, 2020 August 1
5 
6  Author: Sandro Furieri a.furieri@lqt.it
7 
8  ------------------------------------------------------------------------------
9 
10  Version: MPL 1.1/GPL 2.0/LGPL 2.1
11 
12  The contents of this file are subject to the Mozilla Public License Version
13  1.1 (the "License"); you may not use this file except in compliance with
14  the License. You may obtain a copy of the License at
15  http://www.mozilla.org/MPL/
16 
17 Software distributed under the License is distributed on an "AS IS" basis,
18 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
19 for the specific language governing rights and limitations under the
20 License.
21 
22 The Original Code is the SpatiaLite library
23 
24 The Initial Developer of the Original Code is Alessandro Furieri
25 
26 Portions created by the Initial Developer are Copyright (C) 2015-2021
27 the Initial Developer. All Rights Reserved.
28 
29 Contributor(s):
30 
31 Alternatively, the contents of this file may be used under the terms of
32 either the GNU General Public License Version 2 or later (the "GPL"), or
33 the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
34 in which case the provisions of the GPL or the LGPL are applicable instead
35 of those above. If you wish to allow use of your version of this file only
36 under the terms of either the GPL or the LGPL, and not to allow others to
37 use your version of this file under the terms of the MPL, indicate your
38 decision by deleting the provisions above and replace them with the notice
39 and other provisions required by the GPL or the LGPL. If you do not delete
40 the provisions above, a recipient may use your version of this file under
41 the terms of any one of the MPL, the GPL or the LGPL.
42 
43 */
44 
45 
46 /**
47  \file gaia_network.h
48 
49  Topology-Network handling functions and constants
50  */
51 
52 #ifndef DOXYGEN_SHOULD_SKIP_THIS
53 /* stdio.h included for FILE objects. */
54 #include <stdio.h>
55 #ifdef DLL_EXPORT
56 #define GAIANET_DECLARE __declspec(dllexport)
57 #else
58 #define GAIANET_DECLARE extern
59 #endif
60 #endif
61 
62 #ifndef _GAIANET_H
63 #ifndef DOXYGEN_SHOULD_SKIP_THIS
64 #define _GAIANET_H
65 #endif
66 
67 #ifdef __cplusplus
68 extern "C"
69 {
70 #endif
71 
72 /**
73  Typedef for Topology-Network Accessor Object (opaque, hidden)
74 
75  \sa GaiaNetworkAccessorPtr
76  */
77     typedef struct gaia_network_accessor GaiaNetworkAccessor;
78 /**
79  Typedef for Network Accessor Object pointer (opaque, hidden)
80 
81  \sa GaiaNetworkAccessor
82  */
83     typedef struct gaia_network_accessor *GaiaNetworkAccessorPtr;
84 
85 /**
86  returns the last Topology-Network exception (if any)
87 
88  \param network_name unique name identifying the Topology-Network.
89 
90  \return pointer to the last Topology-Network error message: may be NULL if
91  no Topology error is currently pending.
92  */
93     GAIANET_DECLARE const char *gaiaNetworkGetLastException (const char
94 							     *network_name);
95 
96 /**
97  creates a new Topology-Network and all related DB objects
98 
99  \param handle pointer to the current DB connection.
100  \param network_name unique name identifying the Topology-Network.
101  \param spatial boolean: if TRUE this Topology-Network will be assumed
102  to be of the Spatial type, otherwise a Logical Network will be assumed.
103  \param srid a spatial reference identifier (only applies to Spatial
104  Networks).
105  \param has_z boolean: if TRUE this Topology-Network supports 3D (XYZ)
106  (only applies to Spatial Networks).
107  \param allow_coincident boolean: if TRUE coincident Nodes will be
108  tolerated, otherwise a coincident Node condition will raise an exception.
109  This argument only applies to Spatial Networks and is meaningless for
110  Logical Networks.
111 
112  \return 0 on failure: any other value on success.
113 
114  \sa gaiaNetworkDrop
115  */
116     GAIANET_DECLARE int gaiaNetworkCreate (sqlite3 * handle,
117 					   const char *network_name,
118 					   int spatial, int srid, int has_z,
119 					   int allow_coincident);
120 
121 /**
122  completely drops an already existing Topology-Network and removes all related DB objects
123 
124  \param handle pointer to the current DB connection.
125  \param network_name unique name identifying the Topology-Network.
126 
127  \return 0 on failure: any other value on success.
128 
129  \sa gaiaNetworkCreate
130  */
131     GAIANET_DECLARE int gaiaNetworkDrop (sqlite3 * handle,
132 					 const char *network_name);
133 
134 /**
135  creates an opaque Topology-Network Accessor object starting from its DB configuration
136 
137  \param handle pointer to the current DB connection.
138  \param cache pointer to the opaque Cache Object supporting the DB connection
139  \param network_name unique name identifying the Topology-Network.
140 
141  \return the pointer to newly created Topology-Network Accessor Object:
142  NULL on failure.
143 
144  \sa gaiaNetworkCreate, gaiaNetworkDestroy, gaiaNetworkFromCache,
145  gaiaGetNetwork
146 
147  \note you are responsible to destroy (before or after) any allocated
148  Topology-Network Accessor Object. The Topology-Network Accessor once
149  created will be preserved within the internal connection cache for
150  future references.
151  */
152     GAIANET_DECLARE GaiaNetworkAccessorPtr gaiaNetworkFromDBMS (sqlite3 *
153 								handle,
154 								const void
155 								*cache,
156 								const char
157 								*network_name);
158 
159 /**
160  retrieves a Topology configuration from DB
161 
162  \param handle pointer to the current DB connection.
163  \param cache pointer to the opaque Cache Object supporting the DB connection
164  \param net_name unique name identifying the Topology-Network.
165  \param network_name on completion will point to the real Topology-Network name.
166  \param spatial on completion will report if the Topology-Network is of
167  the Spatial or Logical type.
168  \param srid on completion will contain the Topology-Network SRID.
169  \param has_z on completion will report if the Topology-Network is of the 3D type.
170  \param allow_coincident on completion will report if the Topology-Network
171  tolerates a Coindident Nodes condition without raising an exception.
172 
173  \return 1 on success: NULL on failure.
174 
175  \sa gaiaNetworkCreate, gaiaNetworkDestroy, gaiaNetworkFromCache,
176  gaiaGetNetwork
177  */
178     GAIANET_DECLARE int gaiaReadNetworkFromDBMS (sqlite3 *
179 						 handle,
180 						 const char
181 						 *net_name,
182 						 char **network_name,
183 						 int *spatial, int *srid,
184 						 int *has_z,
185 						 int *allow_coincident);
186 
187 /**
188  retrieves an already defined opaque Topology-Network Accessor object from the
189  internal connection cache
190 
191  \param cache pointer to the opaque Cache Object supporting the DB connection
192  \param network_name unique name identifying the Topology-Network.
193 
194  \return pointer to an already existing Topology-Network Accessor Object: NULL on failure.
195 
196  \sa gaiaNetworkCreate, gaiaNetworkDestroy, gaiaNetworkFromDBMS,
197  gaiaGetNetwork
198  */
199     GAIANET_DECLARE GaiaNetworkAccessorPtr gaiaNetworkFromCache (const void
200 								 *cache,
201 								 const char
202 								 *network_name);
203 
204 /**
205  will attempt to return a reference to a Topology-Network Accessor object
206 
207  \param handle pointer to the current DB connection.
208  \param cache pointer to the opaque Cache Object supporting the DB connection
209  \param network_name unique name identifying the Topology-Network.
210 
211  \return pointer to Topology-Network Accessor Object: NULL on failure.
212 
213  \sa gaiaNetworkCreate, gaiaNetworkDestroy, gaiaNetworkFromCache,
214  gaiaNetworkFromDBMS
215 
216  \note if a corresponding Topology-Network Accessor Object is already defined
217  will return a pointer to such Objet. Otherwise an attempt will be made
218  in order to create a new Topology-Network Accessor object starting from
219  its DB configuration.
220  */
221     GAIANET_DECLARE GaiaNetworkAccessorPtr gaiaGetNetwork (sqlite3 *
222 							   handle,
223 							   const void
224 							   *cache,
225 							   const char
226 							   *network_name);
227 
228 /**
229  destroys a Topology-Network Accessor object and any related memory allocation
230 
231  \param ptr pointer to the Topology-Network Accessor Object to be destroyed.
232 
233  \sa gaiaNetworkFromDBMS
234  */
235     GAIANET_DECLARE void gaiaNetworkDestroy (GaiaNetworkAccessorPtr ptr);
236 
237 /**
238  Adds an isolated node into the Topology-Network
239 
240  \param ptr pointer to the Topology-Network Accessor Object.
241  \param pt pointer to the Node Geometry.
242 
243  \return the ID of the inserted Node; a negative number on failure.
244 
245  \sa gaiaNetworkFromDBMS, gaiaMoveIsoNetNode, gaiaRemIsoNetNode,
246  gaiaAddLink
247  */
248     GAIANET_DECLARE sqlite3_int64 gaiaAddIsoNetNode (GaiaNetworkAccessorPtr
249 						     ptr, gaiaPointPtr pt);
250 
251 /**
252  Moves an isolated node in a Topology-Network from one point to another
253 
254  \param ptr pointer to the Topology-Network Accessor Object.
255  \param node the unique identifier of node.
256  \param pt pointer to the Node Geometry.
257 
258  \return 1 on success; 0 on failure.
259 
260  \sa gaiaNetworkFromDBMS, gaiaAddIsoNetNode, gaiaRemIsoNetNode
261  */
262     GAIANET_DECLARE int gaiaMoveIsoNetNode (GaiaNetworkAccessorPtr ptr,
263 					    sqlite3_int64 node,
264 					    gaiaPointPtr pt);
265 
266 /**
267  Removes an isolated node from a Topology-Network
268 
269  \param ptr pointer to the Topology-Network Accessor Object.
270  \param node the unique identifier of node.
271 
272  \return 1 on success; 0 on failure.
273 
274  \sa gaiaNetworkFromDBMS, gaiaAddIsoNetNode, gaiaMoveIsoNetNode
275  */
276     GAIANET_DECLARE int gaiaRemIsoNetNode (GaiaNetworkAccessorPtr ptr,
277 					   sqlite3_int64 node);
278 
279 /**
280  Adds a link into the Topology-Network
281 
282  \param ptr pointer to the Topology-Network Accessor Object.
283  \param start_node the Start Node's unique identifier.
284  \param end_node the End Node unique identifier.
285  \param ln pointer to the Link Geometry.
286 
287  \return the ID of the inserted Link; a negative number on failure.
288 
289  \sa gaiaNetworkFromDBMS, gaiaAddIsoNetNode, gaiaChangeLinkGeom,
290  gaiaRemoveLink, gaiaNewLogLinkSplit, gaiaModLogLinkSplit,
291  gaiaNewGeoLinkSplit, gaiaModGeoLinkSplit, gaiaNewLinkHeal,
292  gaiaModLinkHeal
293  */
294     GAIANET_DECLARE sqlite3_int64 gaiaAddLink (GaiaNetworkAccessorPtr ptr,
295 					       sqlite3_int64 start_node,
296 					       sqlite3_int64 end_node,
297 					       gaiaLinestringPtr ln);
298 
299 /**
300  Changes the shape of a Link without affecting the Topology-Network structure
301 
302  \param ptr pointer to the Topology-Network Accessor Object.
303  \param link_id the Link unique identifier.
304  \param ln pointer to the Link Geometry.
305 
306  \return 1 on success; 0 on failure.
307 
308  \sa gaiaNetworkFromDBMS, gaiaAddLink, gaiaRemoveLink
309  */
310     GAIANET_DECLARE int gaiaChangeLinkGeom (GaiaNetworkAccessorPtr ptr,
311 					    sqlite3_int64 link_id,
312 					    gaiaLinestringPtr ln);
313 
314 /**
315  Removes a Link from a Topology-Network
316 
317  \param ptr pointer to the Topology-Network Accessor Object.
318  \param link the unique identifier of link.
319 
320  \return 1 on success; 0 on failure.
321 
322  \sa gaiaNetworkFromDBMS, gaiaAddLink
323  */
324     GAIANET_DECLARE int gaiaRemoveLink (GaiaNetworkAccessorPtr ptr,
325 					sqlite3_int64 link);
326 
327 /**
328  Split a logical link, replacing it with two new links.
329 
330  \param ptr pointer to the Topology-Network Accessor Object.
331  \param link the unique identifier of the link to be split.
332 
333  \return the ID of the inserted Node; a negative number on failure.
334 
335  \sa gaiaNetworkFromDBMS, gaiaAddLink, gaiaModLogLinkSplit,
336  gaiaNewGeoLinkSplit, gaiaModGeoLinkSplit, gaiaNewLinkHeal,
337  gaiaModLinkHeal
338  */
339     GAIANET_DECLARE sqlite3_int64 gaiaNewLogLinkSplit (GaiaNetworkAccessorPtr
340 						       ptr, sqlite3_int64 link);
341 
342 /**
343  Split a logical link, modifying the original link and adding a new one.
344 
345  \param ptr pointer to the Topology-Network Accessor Object.
346  \param link the unique identifier of the link to be split.
347 
348  \return the ID of the inserted Node; a negative number on failure.
349 
350  \sa gaiaNetworkFromDBMS, gaiaAddLink, gaiaNewLogLinkSplit,
351  gaiaNewGeoLinkSplit, gaiaModGeoLinkSplit, gaiaNewLinkHeal,
352  gaiaModLinkHeal
353  */
354     GAIANET_DECLARE sqlite3_int64 gaiaModLogLinkSplit (GaiaNetworkAccessorPtr
355 						       ptr, sqlite3_int64 link);
356 
357 /**
358  Split a spatial link by a node, replacing it with two new links.
359 
360  \param ptr pointer to the Topology-Network Accessor Object.
361  \param link the unique identifier of the link to be split.
362  \param pt pointer to the Node Geometry.
363 
364  \return the ID of the inserted Node; a negative number on failure.
365 
366  \sa gaiaNetworkFromDBMS, gaiaAddLink, gaiaNewLogLinkSplit,
367  gaiaModLogLinkSplit, gaiaModGeoLinkSplit, gaiaNewLinkHeal,
368  gaiaModLinkHeal
369  */
370     GAIANET_DECLARE sqlite3_int64 gaiaNewGeoLinkSplit (GaiaNetworkAccessorPtr
371 						       ptr,
372 						       sqlite3_int64 link,
373 						       gaiaPointPtr pt);
374 
375 /**
376  Split a spatial link by a node, modifying the original link and adding
377  a new one.
378 
379  \param ptr pointer to the Topology-Network Accessor Object.
380  \param link the unique identifier of the link to be split.
381  \param pt pointer to the Node Geometry.
382 
383  \return the ID of the inserted Node; a negative number on failure.
384 
385  \sa gaiaNetworkFromDBMS, gaiaAddLink, gaiaNewLogLinkSplit,
386  gaiaModLogLinkSplit, gaiaNewGeoLinkSplit, gaiaNewLinkHeal,
387  gaiaModLinkHeal
388  */
389     GAIANET_DECLARE sqlite3_int64 gaiaModGeoLinkSplit (GaiaNetworkAccessorPtr
390 						       ptr,
391 						       sqlite3_int64 link,
392 						       gaiaPointPtr pt);
393 
394 /**
395  Heal two links by deleting the node connecting them, deleting both links,
396  and replacing them with a new link whose direction is the same as the
397  first link provided.
398 
399  \param ptr pointer to the Topology-Network Accessor Object.
400  \param link the unique identifier of the first link to be healed.
401  \param anotherlink the unique identifier of the second link to be healed.
402 
403  \return the ID of the removed Node; a negative number on failure.
404 
405  \sa gaiaNetworkFromDBMS, gaiaAddLink, gaiaNewLogLinkSplit,
406  gaiaModLogLinkSplit, gaiaNewGeoLinkSplit, gaiaModGeoLinkSplit,
407  gaiaModLinkHeal
408  */
409     GAIANET_DECLARE sqlite3_int64 gaiaNewLinkHeal (GaiaNetworkAccessorPtr
410 						   ptr, sqlite3_int64 link,
411 						   sqlite3_int64 anotherlink);
412 
413 /**
414  Heal two links by deleting the node connecting them, modfying the first
415  link provided, and deleting the second link.
416  *
417  \param ptr pointer to the Topology-Network Accessor Object.
418  \param link the unique identifier of the first link to be healed.
419  \param anotherlink the unique identifier of the second link to be healed.
420 
421  \return the ID of the removed Node; a negative number on failure.
422 
423  \sa gaiaNetworkFromDBMS, gaiaAddLink, gaiaNewLogLinkSplit,
424  gaiaModLogLinkSplit, gaiaNewGeoLinkSplit, gaiaModGeoLinkSplit,
425  gaiaNewLinkHeal
426  */
427     GAIANET_DECLARE sqlite3_int64 gaiaModLinkHeal (GaiaNetworkAccessorPtr
428 						   ptr, sqlite3_int64 link,
429 						   sqlite3_int64 anotherlink);
430 
431 /**
432  Creates a temporary table containing a validation report for a given
433  Logical TopoNet.
434 
435  \param ptr pointer to the Topology Accessor Object.
436 
437  \return 1 on success; 0 on failure.
438 
439  \sa gaiaNetworkFromDBMS
440  */
441     GAIANET_DECLARE int gaiaValidLogicalNet (GaiaNetworkAccessorPtr ptr);
442 
443 /**
444  Creates a temporary table containing a validation report for a given
445  Spatial TopoNet.
446 
447  \param ptr pointer to the Topology Accessor Object.
448 
449  \return 1 on success; 0 on failure.
450 
451  \sa gaiaNetworkFromDBMS
452  */
453     GAIANET_DECLARE int gaiaValidSpatialNet (GaiaNetworkAccessorPtr ptr);
454 
455 /**
456  Find the ID of a NetNode at a Point location
457 
458  \param ptr pointer to the Topology-Network Accessor Object.
459  \param pt pointer to the Point Geometry.
460  \param tolerance approximation factor.
461 
462  \return the ID of a NetNode; -1 on failure.
463 
464  \sa gaiaNetworkFromDBMS
465  */
466     GAIANET_DECLARE sqlite3_int64
467 	gaiaGetNetNodeByPoint (GaiaNetworkAccessorPtr ptr, gaiaPointPtr pt,
468 			       double tolerance);
469 
470 /**
471  Find the ID of a Link at a Point location
472 
473  \param ptr pointer to the Topology-Network Accessor Object.
474  \param pt pointer to the Point Geometry.
475  \param tolerance approximation factor.
476 
477  \return the ID of a Link; -1 on failure.
478 
479  \sa gaiaNetworkFromDBMS
480  */
481     GAIANET_DECLARE sqlite3_int64
482 	gaiaGetLinkByPoint (GaiaNetworkAccessorPtr ptr, gaiaPointPtr pt,
483 			    double tolerance);
484 
485 /**
486  Populates a Network by importing a whole GeoTable
487 
488  \param ptr pointer to the Network Accessor Object.
489  \param db-prefix prefix of the DB containing the input GeoTable.
490  If NULL the "main" DB will be intended by default.
491  \param table name of the input GeoTable.
492  \param column name of the input Geometry Column.
493  Could be NULL is the input table has just a single Geometry Column.
494 
495  \return 1 on success; -1 on failure (will raise an exception).
496 
497  \sa gaiaNetworkFromDBMS
498  */
499     GAIANET_DECLARE int
500 	gaiaTopoNet_FromGeoTable (GaiaNetworkAccessorPtr ptr,
501 				  const char *db_prefix, const char *table,
502 				  const char *column);
503 
504 /**
505  Return a Point geometry (seed) identifying a Network Link
506 
507  \param ptr pointer to the Network Accessor Object.
508  \param link the unique identifier of the link.
509 
510  \return pointer to Geomtry (point); NULL on failure.
511 
512  \sa gaiaNetworkFromDBMS
513  */
514     GAIANET_DECLARE gaiaGeomCollPtr
515 	gaiaGetLinkSeed (GaiaNetworkAccessorPtr ptr, sqlite3_int64 link);
516 
517 /**
518  Ensures that all Links on a Topology-Network will have not less
519  than three vertices; for all Links found being simple two-points
520  segments a third intermediate point will be interpolated.
521 
522  \param ptr pointer to the Network Accessor Object.
523 
524  \return the total number of changed Links; a negativa number on error
525 
526  \sa gaiaNetworkFromDBMS
527  */
528     GAIANET_DECLARE int
529 	gaiaTopoNet_DisambiguateSegmentLinks (GaiaNetworkAccessorPtr ptr);
530 
531 /**
532  Will update all Seeds for a Topology-Network
533 
534  \param ptr pointer to the Network Accessor Object.
535  \param mode if set to 0 a full update of all Seeds will be performed,
536  otherwise an incremental update will happen.
537 
538  \return 1 on success; 0 on failure.
539 
540  \sa gaiaNetworkFromDBMS
541  */
542     GAIANET_DECLARE int
543 	gaiaTopoNetUpdateSeeds (GaiaNetworkAccessorPtr ptr, int mode);
544 
545 /**
546  Extracts a Simple Features Table out from a Network by matching
547  Network Seeds to a given reference Table.
548 
549  \param ptr pointer to the Network Accessor Object.
550  \param db-prefix prefix of the DB containing the reference GeoTable.
551  If NULL the "main" DB will be intended by default.
552  \param ref_table name of the reference GeoTable.
553  \param ref_column name of the reference Geometry Column.
554  Could be NULL is the reference table has just a single Geometry Column.
555  \param out_table name of the output table to be created and populated.
556  \param with_spatial_index boolean flag: if set to TRUE (non ZERO) a Spatial
557  Index supporting the output table will be created.
558 
559  \return 1 on success; -1 on failure (will raise an exception).
560 
561  \sa gaiaNetworkFromDBMS
562  */
563     GAIANET_DECLARE int
564 	gaiaTopoNet_ToGeoTable (GaiaNetworkAccessorPtr ptr,
565 				const char *db_prefix, const char *ref_table,
566 				const char *ref_column, const char *out_table,
567 				int with_spatial_index);
568 
569 /**
570  Extracts a simplified/generalized Simple Features Table out from a Network
571  by matching Network Seeds to a given reference Table.
572 
573  \param ptr pointer to the Network Accessor Object.
574  \param db-prefix prefix of the DB containing the reference GeoTable.
575  If NULL the "main" DB will be intended by default.
576  \param ref_table name of the reference GeoTable.
577  \param ref_column name of the reference Geometry Column.
578  Could be NULL is the reference table has just a single Geometry Column.
579  \param out_table name of the output table to be created and populated.
580  \param tolerance approximation radius required by the Douglar-Peucker
581  simplification algorithm.
582  \param with_spatial_index boolean flag: if set to TRUE (non ZERO) a Spatial
583  Index supporting the output table will be created.
584 
585  \return 1 on success; -1 on failure (will raise an exception).
586 
587  \sa gaiaNetworkFromDBMS
588  */
589     GAIANET_DECLARE int
590 	gaiaTopoNet_ToGeoTableGeneralize (GaiaNetworkAccessorPtr ptr,
591 					  const char *db_prefix,
592 					  const char *ref_table,
593 					  const char *ref_column,
594 					  const char *out_table,
595 					  double tolerance,
596 					  int with_spatial_index);
597 
598 /**
599  Creates and populates a Table containing a comprehensive report
600  about all intesections between the Links of some Network and
601  a given reference Table of the Linestring/Multilinestring type.
602 
603  \param ptr pointer to the Network Accessor Object.
604  \param db-prefix prefix of the DB containing the reference GeoTable.
605  If NULL the "main" DB will be intended by default.
606  \param ref_table name of the reference GeoTable.
607  \param ref_column name of the reference Geometry Column.
608  Could be NULL is the reference table has just a single Geometry Column.
609  \param out_table name of the output output table to be created and populated.
610 
611  \return 1 on success; -1 on failure (will raise an exception).
612 
613  \sa gaiaNetworkFromDBMS
614  */
615     GAIANET_DECLARE int
616 	gaiaTopoNet_LineLinksList (GaiaNetworkAccessorPtr ptr,
617 				   const char *db_prefix, const char *ref_table,
618 				   const char *ref_column,
619 				   const char *out_table);
620 
621 
622 #ifdef __cplusplus
623 }
624 #endif
625 
626 
627 #endif				/* _GAIANET_H */
628