1 /******************************************************************************
2 *  LibGHT, software to manage point clouds.
3 *  LibGHT is free and open source software provided by the Government of Canada
4 *  Copyright (c) 2012 Natural Resources Canada
5 *
6 *  Nouri Sabo <nsabo@NRCan.gc.ca>, Natural Resources Canada
7 *  Paul Ramsey <pramsey@opengeo.org>, OpenGeo
8 *
9 ******************************************************************************/
10 
11 #include "ght_core.h"
12 
13 #ifndef _GHT_H
14 #define _GHT_H
15 
16 typedef void* GhtDimensionPtr;
17 typedef void* GhtSchemaPtr;
18 typedef void* GhtWriterPtr;
19 typedef void* GhtReaderPtr;
20 typedef void* GhtTreePtr;
21 typedef void* GhtNodeListPtr;
22 typedef void* GhtNodePtr;
23 typedef void* GhtAttributePtr;
24 typedef GhtConfig* GhtConfigPtr;
25 
26 
27 /***********************************************************************
28 *   NODE
29 */
30 
31 /** Create a new node from a hash */
32 GhtErr ght_node_new_from_hash(const GhtHash *hash, GhtNodePtr *node);
33 
34 /** Create a new code from a coordinate */
35 GhtErr ght_node_new_from_coordinate(const GhtCoordinate *coord, unsigned int resolution, GhtNodePtr *node);
36 
37 /** Get the coordinates represented by the node */
38 GhtErr ght_node_get_coordinate(const GhtNodePtr node, GhtCoordinate *coord);
39 
40 /** Add a new attribute to the node */
41 GhtErr ght_node_add_attribute(GhtNodePtr node, GhtAttributePtr attribute);
42 
43 /** Get the attribute list handing off the node */
44 GhtErr ght_node_get_attributes(const GhtNodePtr node, GhtAttributePtr *attr);
45 
46 
47 /***********************************************************************
48 *   NODELIST
49 */
50 
51 /** Create an empty nodelist */
52 GhtErr ght_nodelist_new(int capacity, GhtNodeListPtr *nodelist);
53 
54 /** How many nodes in this GhtNodeList? */
55 GhtErr ght_nodelist_get_num_nodes(const GhtNodeListPtr nodelist, int *num_nodes);
56 
57 /** Get a GhtNode by index number */
58 GhtErr ght_nodelist_get_node(const GhtNodeListPtr nodelist, int index, GhtNodePtr *node);
59 
60 /** Add a new node to a nodelist */
61 GhtErr ght_nodelist_add_node(GhtNodeListPtr nodelist, GhtNodePtr node);
62 
63 /** Free a nodelist, and optionally all the nodes referenced by the list */
64 GhtErr ght_nodelist_free_deep(GhtNodeListPtr nodelist);
65 
66 /** Free a nodelist, but not the nodes it holds */
67 GhtErr ght_nodelist_free_shallow(GhtNodeListPtr nodelist);
68 
69 
70 /***********************************************************************
71 *   ATTRIBUTE
72 */
73 
74 /** Allocate a new attribute and fill in the value from a double */
75 GhtErr ght_attribute_new_from_double(const GhtDimensionPtr dim, double val, GhtAttributePtr *attr);
76 
77 /** Read the next attribute from an attribute list */
78 GhtErr ght_attribute_get_next(const GhtAttributePtr attr, GhtAttributePtr *nextattr);
79 
80 /** Get the dimension associated with a GhtAttribute */
81 GhtErr ght_attribute_get_dimension(const GhtAttributePtr attr, const GhtDimensionPtr *dim);
82 
83 /***********************************************************************
84 *   DIMENSION
85 */
86 
87 /** Create a populated dimension */
88 GhtErr ght_dimension_new_from_parameters(const char *name, const char *desc, GhtType type, double scale, double offset, GhtDimensionPtr *dim);
89 
90 /** What's the name of this dimension? */
91 GhtErr ght_dimension_get_name(const GhtDimensionPtr dim, const char **name);
92 
93 /** What's the type of this dimension? */
94 GhtErr ght_dimension_get_type(const GhtDimensionPtr dim, GhtType *type);
95 
96 /** What's the index of this dimension? */
97 GhtErr ght_dimension_get_index(const GhtDimensionPtr dim, int *index);
98 
99 
100 /***********************************************************************
101 *   SCHEMA
102 */
103 
104 /** Allocate a blank GhtSchemaPtr */
105 GhtErr ght_schema_new(GhtSchemaPtr *schema);
106 
107 /** Write out an XML representation of a GhtSchemaPtr */
108 GhtErr ght_schema_to_xml_file(const GhtSchemaPtr schema, const char *filename);
109 
110 /** Write out an XML representation of a GhtSchemaPtr */
111 GhtErr ght_schema_from_xml_file(const char *filename, GhtSchemaPtr *schema);
112 
113 /** Append a GhtDimension to the GhtSchemaPtr */
114 GhtErr ght_schema_add_dimension(GhtSchemaPtr schema, GhtDimensionPtr dim);
115 
116 /** How many dimensions in this schema? */
117 GhtErr ght_schema_get_num_dimensions(const GhtSchemaPtr schema, unsigned int *num_dims);
118 
119 /** Read a dimension */
120 GhtErr ght_schema_get_dimension_by_index(const GhtSchemaPtr schema, int i, GhtDimensionPtr *dim);
121 
122 /** Read a dimension */
123 GhtErr ght_schema_get_dimension_by_name(const GhtSchemaPtr schema, const char *name, GhtDimensionPtr *dim);
124 
125 /** Free an existing schema */
126 GhtErr ght_schema_free(GhtSchemaPtr schema);
127 
128 
129 /***********************************************************************
130 *   TREE
131 */
132 
133 /** Allocate a new tree and initialize config parameters */
134 GhtErr ght_tree_new(const GhtSchemaPtr a, GhtTreePtr *tree);
135 
136 /** Build a tree from a linear nodelist */
137 GhtErr ght_tree_from_nodelist(const GhtSchemaPtr schema, GhtNodeListPtr nlist, GhtConfigPtr config, GhtTreePtr *tree);
138 
139 /** Free a GhtTree from memory, including nodes and schema */
140 GhtErr ght_tree_free(GhtTreePtr tree);
141 
142 /** Add a GhtNode to a GhtTreePtr */
143 GhtErr ght_tree_insert_node(GhtTreePtr tree, GhtNodePtr node);
144 
145 /** Write a GhtTree to memory or file */
146 GhtErr ght_tree_write(const GhtTreePtr tree, GhtWriterPtr writer);
147 
148 /** Read the top level hash key off the GhtTreePtr */
149 GhtErr ght_tree_get_hash(const GhtTreePtr tree, GhtHash **hash);
150 
151 /** Read the schema from the GhtTree */
152 GhtErr ght_tree_get_schema(const GhtTreePtr tree, GhtSchemaPtr *schema);
153 
154 /** Read the point cound from the GhtTree */
155 GhtErr ght_tree_get_numpoints(const GhtTreePtr tree, int *numpoints);
156 
157 /** Calculate the spatial extent of a GhtTree */
158 GhtErr ght_tree_get_extent(const GhtTreePtr tree, GhtArea *area);
159 
160 /** Allocate new tree with only nodes that meet the filter condition */
161 GhtErr ght_tree_filter_greater_than(const GhtTreePtr tree, const char *dimname, double value, GhtTreePtr *tree_filtered);
162 
163 /** Allocate new tree with only nodes that meet the filter condition */
164 GhtErr ght_tree_filter_less_than(const GhtTreePtr tree, const char *dimname, double value, GhtTreePtr *tree_filtered);
165 
166 /** Allocate new tree with only nodes that meet the filter condition */
167 GhtErr ght_tree_filter_between(const GhtTreePtr tree, const char *dimname, double value1, double value2, GhtTreePtr *tree_filtered);
168 
169 /** Allocate new tree with only nodes that meet the filter condition */
170 GhtErr ght_tree_filter_equal(const GhtTreePtr tree, const char *dimname, double value, GhtTreePtr *tree_filtered);
171 
172 /** Compact all the attributes from 'Z' onwards */
173 GhtErr ght_tree_compact_attributes(GhtTreePtr tree);
174 
175 /** Write a GhtTree to memory or file */
176 GhtErr ght_tree_write(const GhtTreePtr tree, GhtWriterPtr writer);
177 
178 /** Write a GhtTree to memory of file */
179 GhtErr ght_tree_read(GhtReaderPtr reader, GhtTreePtr *tree);
180 
181 /** Set up a tree configuration with defaults */
182 GhtErr ght_config_init(GhtConfigPtr config);
183 
184 
185 /***********************************************************************
186 *   WRITER
187 */
188 
189 /** Create a new file-based writer */
190 GhtErr ght_writer_new_file(const char *filename, GhtWriterPtr *writer);
191 
192 /** Create a new memory-backed writer */
193 GhtErr ght_writer_new_mem(GhtWriterPtr *writer);
194 
195 /** Read current size of writen bytes */
196 GhtErr ght_writer_get_size(GhtWriterPtr writer, size_t *size);
197 
198 /** Copy bytes from memory writer into external buffer */
199 GhtErr ght_writer_get_bytes(GhtWriterPtr writer, unsigned char *bytes);
200 
201 /** Close filehandle if necessary and free all memory along with writer */
202 GhtErr ght_writer_free(GhtWriterPtr writer);
203 
204 
205 
206 /***********************************************************************
207 *   READER
208 */
209 
210 /** Create a new file-based reader */
211 GhtErr ght_reader_new_file(const char *filename, const GhtSchemaPtr schema, GhtReaderPtr *reader);
212 
213 /** Create a new memory-based reader */
214 GhtErr ght_reader_new_mem(const unsigned char *bytes_start, size_t bytes_size, const GhtSchemaPtr schema, GhtReaderPtr *reader);
215 
216 /** Close filehandle if necessary and free all memory along with reader */
217 GhtErr ght_reader_free(GhtReaderPtr reader);
218 
219 
220 
221 #endif