59 | This is a browser-based demonstration of clj-proj, 60 | a Clojure/ClojureScript library that provides bindings to PROJ 61 | (cartographic projections and coordinate transformations library). 62 |
63 |64 | Project Links: 65 | GitHub Repository | 66 | Documentation | 67 | Clojars | 68 | npm 69 |
70 |71 | This demo runs PROJ directly in your browser using WebAssembly (WASM). The entire PROJ library, including its 72 | coordinate reference system database, has been compiled to WASM and runs entirely client-side. No server 73 | communication is required for the transformations. 74 |
75 |76 | How it's built: 77 |
78 |96 | See the README for comprehensive documentation, 97 | installation instructions, and usage examples for both Clojure and JavaScript environments. 98 |
99 |
22 | * // Initialize (auto-selects best backend: native FFI or GraalVM WASM)
23 | * PROJ.init();
24 | *
25 | * // Create a context and transformation
26 | * Object ctx = PROJ.contextCreate();
27 | * Object transform = PROJ.createCrsToCrs(ctx, "EPSG:4326", "EPSG:2249");
28 | *
29 | * // Transform coordinates
30 | * Object coords = PROJ.coordArray(1);
31 | * PROJ.setCoords(coords, new double[][]{{42.36, -71.05}});
32 | * PROJ.transArray(transform, coords, 1);
33 | *
34 | */
35 | public class PROJ {
36 |
37 | private static final String NS = "net.willcohen.proj.proj";
38 | private static boolean nsLoaded = false;
39 |
40 | // Clojure function references (lazily loaded)
41 | private static IFn initFn;
42 | private static IFn forceGraalFn;
43 | private static IFn forceFfiFn;
44 | private static IFn toggleGraalFn;
45 | private static IFn isFfiFn;
46 | private static IFn isGraalFn;
47 | private static IFn isNodeFn;
48 | private static IFn contextCreateFn;
49 | private static IFn contextPtrFn;
50 | private static IFn contextDatabasePathFn;
51 | private static IFn isContextFn;
52 | private static IFn contextSetDatabasePathFn;
53 | private static IFn coordArrayFn;
54 | private static IFn coordToCoordArrayFn;
55 | private static IFn setCoordsFn;
56 | private static IFn setCoordFn;
57 | private static IFn setColFn;
58 | private static IFn setXcolFn;
59 | private static IFn setYcolFn;
60 | private static IFn setZcolFn;
61 | private static IFn setTcolFn;
62 | private static IFn errorCodeToStringFn;
63 |
64 | // Generated PROJ functions (most commonly used)
65 | private static IFn createCrsToCrsFn;
66 | private static IFn createCrsToCrsFromPjFn;
67 | private static IFn createFromDatabaseFn;
68 | private static IFn transArrayFn;
69 | private static IFn getAuthoritiesFromDatabaseFn;
70 | private static IFn getCodesFromDatabaseFn;
71 | private static IFn contextDestroyFn;
72 | private static IFn destroyFn;
73 |
74 | private static synchronized void ensureLoaded() {
75 | if (!nsLoaded) {
76 | IFn require = Clojure.var("clojure.core", "require");
77 | require.invoke(Clojure.read(NS));
78 | nsLoaded = true;
79 | }
80 | }
81 |
82 | private static IFn getVar(String name) {
83 | ensureLoaded();
84 | return Clojure.var(NS, name);
85 | }
86 |
87 | private static Keyword kw(String name) {
88 | return Keyword.intern(name);
89 | }
90 |
91 | private static IPersistentMap map(Object... kvs) {
92 | return PersistentHashMap.create(kvs);
93 | }
94 |
95 | // --- Initialization ---
96 |
97 | /**
98 | * Initialize PROJ library. Auto-selects the best available backend:
99 | * native FFI if platform libraries are available, otherwise GraalVM WASM.
100 | */
101 | public static void init() {
102 | if (initFn == null) initFn = getVar("init!");
103 | initFn.invoke();
104 | }
105 |
106 | /**
107 | * Force use of GraalVM WASM backend even if native libraries are available.
108 | */
109 | public static void forceGraal() {
110 | if (forceGraalFn == null) forceGraalFn = getVar("force-graal!");
111 | forceGraalFn.invoke();
112 | }
113 |
114 | /**
115 | * Force use of native FFI backend.
116 | */
117 | public static void forceFfi() {
118 | if (forceFfiFn == null) forceFfiFn = getVar("force-ffi!");
119 | forceFfiFn.invoke();
120 | }
121 |
122 | /**
123 | * Toggle between FFI and GraalVM backends.
124 | */
125 | public static void toggleGraal() {
126 | if (toggleGraalFn == null) toggleGraalFn = getVar("toggle-graal!");
127 | toggleGraalFn.invoke();
128 | }
129 |
130 | // --- Implementation checks ---
131 |
132 | /**
133 | * Check if currently using native FFI backend.
134 | * @return true if using FFI
135 | */
136 | public static boolean isFfi() {
137 | if (isFfiFn == null) isFfiFn = getVar("ffi?");
138 | return (Boolean) isFfiFn.invoke();
139 | }
140 |
141 | /**
142 | * Check if currently using GraalVM WASM backend.
143 | * @return true if using GraalVM
144 | */
145 | public static boolean isGraal() {
146 | if (isGraalFn == null) isGraalFn = getVar("graal?");
147 | return (Boolean) isGraalFn.invoke();
148 | }
149 |
150 | /**
151 | * Check if currently using Node.js backend (not applicable on JVM).
152 | * @return true if using Node.js
153 | */
154 | public static boolean isNode() {
155 | if (isNodeFn == null) isNodeFn = getVar("node?");
156 | return (Boolean) isNodeFn.invoke();
157 | }
158 |
159 | // --- Context management ---
160 |
161 | /**
162 | * Create a new PROJ context. Contexts provide thread-safe isolation.
163 | * @return opaque context object
164 | */
165 | public static Object contextCreate() {
166 | if (contextCreateFn == null) contextCreateFn = getVar("context-create");
167 | return contextCreateFn.invoke();
168 | }
169 |
170 | /**
171 | * Get the native pointer from a context.
172 | * @param context the context object
173 | * @return the native pointer
174 | */
175 | public static Object contextPtr(Object context) {
176 | if (contextPtrFn == null) contextPtrFn = getVar("context-ptr");
177 | return contextPtrFn.invoke(context);
178 | }
179 |
180 | /**
181 | * Get the database path from a context.
182 | * @param context the context object
183 | * @return the database path
184 | */
185 | public static String contextDatabasePath(Object context) {
186 | if (contextDatabasePathFn == null) contextDatabasePathFn = getVar("context-database-path");
187 | Object result = contextDatabasePathFn.invoke(context);
188 | return result != null ? result.toString() : null;
189 | }
190 |
191 | /**
192 | * Check if an object is a PROJ context.
193 | * @param obj the object to check
194 | * @return true if it's a context
195 | */
196 | public static boolean isContext(Object obj) {
197 | if (isContextFn == null) isContextFn = getVar("is-context?");
198 | return (Boolean) isContextFn.invoke(obj);
199 | }
200 |
201 | /**
202 | * Set the database path for a context.
203 | * @param context the context object
204 | */
205 | public static void contextSetDatabasePath(Object context) {
206 | if (contextSetDatabasePathFn == null) contextSetDatabasePathFn = getVar("context-set-database-path");
207 | contextSetDatabasePathFn.invoke(context);
208 | }
209 |
210 | /**
211 | * Set the database path for a context.
212 | * @param context the context object
213 | * @param dbPath the database path
214 | */
215 | public static void contextSetDatabasePath(Object context, String dbPath) {
216 | if (contextSetDatabasePathFn == null) contextSetDatabasePathFn = getVar("context-set-database-path");
217 | contextSetDatabasePathFn.invoke(context, dbPath);
218 | }
219 |
220 | // --- Coordinate arrays ---
221 |
222 | /**
223 | * Allocate a coordinate array for n coordinates with 4 dimensions (x, y, z, t).
224 | * @param n number of coordinates
225 | * @return coordinate array object
226 | */
227 | public static Object coordArray(int n) {
228 | if (coordArrayFn == null) coordArrayFn = getVar("coord-array");
229 | return coordArrayFn.invoke(n);
230 | }
231 |
232 | /**
233 | * Allocate a coordinate array for n coordinates with specified dimensions.
234 | * @param n number of coordinates
235 | * @param dims number of dimensions (2, 3, or 4)
236 | * @return coordinate array object
237 | */
238 | public static Object coordArray(int n, int dims) {
239 | if (coordArrayFn == null) coordArrayFn = getVar("coord-array");
240 | return coordArrayFn.invoke(n, dims);
241 | }
242 |
243 | /**
244 | * Convert a single coordinate to a coordinate array.
245 | * @param coord the coordinate as double array
246 | * @return coordinate array object
247 | */
248 | public static Object coordToCoordArray(double[] coord) {
249 | if (coordToCoordArrayFn == null) coordToCoordArrayFn = getVar("coord->coord-array");
250 | return coordToCoordArrayFn.invoke(PersistentVector.create((Object[]) box(coord)));
251 | }
252 |
253 | /**
254 | * Set coordinates in a coordinate array.
255 | * Coordinates are padded to 4 dimensions (x, y, z, t) with zeros if needed.
256 | * @param coordArray the coordinate array
257 | * @param coords array of coordinates, each as [x, y] or [x, y, z] or [x, y, z, t]
258 | */
259 | public static void setCoords(Object coordArray, double[][] coords) {
260 | if (setCoordsFn == null) setCoordsFn = getVar("set-coords!");
261 | // Convert to Clojure vector of vectors, padding to 4 dimensions
262 | Object[] outer = new Object[coords.length];
263 | for (int i = 0; i < coords.length; i++) {
264 | Double[] padded = new Double[4];
265 | for (int j = 0; j < 4; j++) {
266 | padded[j] = (j < coords[i].length) ? coords[i][j] : 0.0;
267 | }
268 | outer[i] = PersistentVector.create((Object[]) padded);
269 | }
270 | setCoordsFn.invoke(coordArray, PersistentVector.create(outer));
271 | }
272 |
273 | /**
274 | * Set a single coordinate in a coordinate array at the given index.
275 | * Coordinate is padded to 4 dimensions (x, y, z, t) with zeros if needed.
276 | * @param coordArray the coordinate array
277 | * @param index the index (0-based)
278 | * @param coord the coordinate values
279 | */
280 | public static void setCoord(Object coordArray, int index, double[] coord) {
281 | if (setCoordFn == null) setCoordFn = getVar("set-coord!");
282 | Double[] padded = new Double[4];
283 | for (int j = 0; j < 4; j++) {
284 | padded[j] = (j < coord.length) ? coord[j] : 0.0;
285 | }
286 | setCoordFn.invoke(coordArray, index, PersistentVector.create((Object[]) padded));
287 | }
288 |
289 | /**
290 | * Set values for a specific column in a coordinate array.
291 | * @param coordArray the coordinate array
292 | * @param colIndex the column index (0=x, 1=y, 2=z, 3=t)
293 | * @param values the values for that column
294 | */
295 | public static void setCol(Object coordArray, int colIndex, double[] values) {
296 | if (setColFn == null) setColFn = getVar("set-col!");
297 | setColFn.invoke(coordArray, colIndex, PersistentVector.create((Object[]) box(values)));
298 | }
299 |
300 | /**
301 | * Set X column values in a coordinate array.
302 | * @param coordArray the coordinate array
303 | * @param values the X values
304 | */
305 | public static void setXcol(Object coordArray, double[] values) {
306 | if (setXcolFn == null) setXcolFn = getVar("set-xcol!");
307 | setXcolFn.invoke(coordArray, PersistentVector.create((Object[]) box(values)));
308 | }
309 |
310 | /**
311 | * Set Y column values in a coordinate array.
312 | * @param coordArray the coordinate array
313 | * @param values the Y values
314 | */
315 | public static void setYcol(Object coordArray, double[] values) {
316 | if (setYcolFn == null) setYcolFn = getVar("set-ycol!");
317 | setYcolFn.invoke(coordArray, PersistentVector.create((Object[]) box(values)));
318 | }
319 |
320 | /**
321 | * Set Z column values in a coordinate array.
322 | * @param coordArray the coordinate array
323 | * @param values the Z values
324 | */
325 | public static void setZcol(Object coordArray, double[] values) {
326 | if (setZcolFn == null) setZcolFn = getVar("set-zcol!");
327 | setZcolFn.invoke(coordArray, PersistentVector.create((Object[]) box(values)));
328 | }
329 |
330 | /**
331 | * Set T (time) column values in a coordinate array.
332 | * @param coordArray the coordinate array
333 | * @param values the T values
334 | */
335 | public static void setTcol(Object coordArray, double[] values) {
336 | if (setTcolFn == null) setTcolFn = getVar("set-tcol!");
337 | setTcolFn.invoke(coordArray, PersistentVector.create((Object[]) box(values)));
338 | }
339 |
340 | // --- Error handling ---
341 |
342 | /**
343 | * Convert a PROJ error code to a human-readable string.
344 | * @param errorCode the error code
345 | * @return description of the error
346 | */
347 | public static String errorCodeToString(int errorCode) {
348 | if (errorCodeToStringFn == null) errorCodeToStringFn = getVar("error-code->string");
349 | Object result = errorCodeToStringFn.invoke(errorCode);
350 | return result != null ? result.toString() : null;
351 | }
352 |
353 | // --- Core PROJ operations (from generated functions) ---
354 |
355 | /**
356 | * Create a transformation between two coordinate reference systems.
357 | * @param context the PROJ context
358 | * @param sourceCrs source CRS (e.g., "EPSG:4326")
359 | * @param targetCrs target CRS (e.g., "EPSG:2249")
360 | * @return transformation object
361 | */
362 | public static Object createCrsToCrs(Object context, String sourceCrs, String targetCrs) {
363 | if (createCrsToCrsFn == null) createCrsToCrsFn = getVar("proj-create-crs-to-crs");
364 | return createCrsToCrsFn.invoke(map(
365 | kw("context"), context,
366 | kw("source-crs"), sourceCrs,
367 | kw("target-crs"), targetCrs
368 | ));
369 | }
370 |
371 | /**
372 | * Create a transformation between two coordinate reference systems using default context.
373 | * @param sourceCrs source CRS (e.g., "EPSG:4326")
374 | * @param targetCrs target CRS (e.g., "EPSG:2249")
375 | * @return transformation object
376 | */
377 | public static Object createCrsToCrs(String sourceCrs, String targetCrs) {
378 | if (createCrsToCrsFn == null) createCrsToCrsFn = getVar("proj-create-crs-to-crs");
379 | return createCrsToCrsFn.invoke(map(
380 | kw("source-crs"), sourceCrs,
381 | kw("target-crs"), targetCrs
382 | ));
383 | }
384 |
385 | /**
386 | * Create a transformation between two CRS objects (PJ pointers).
387 | * This is the same as createCrsToCrs() except that the source and target CRS
388 | * are passed as PJ objects rather than string identifiers.
389 | * @param context the PROJ context
390 | * @param sourceCrs source CRS object (from createFromDatabase or similar)
391 | * @param targetCrs target CRS object (from createFromDatabase or similar)
392 | * @return transformation object
393 | */
394 | public static Object createCrsToCrsFromPj(Object context, Object sourceCrs, Object targetCrs) {
395 | if (createCrsToCrsFromPjFn == null) createCrsToCrsFromPjFn = getVar("proj-create-crs-to-crs-from-pj");
396 | return createCrsToCrsFromPjFn.invoke(map(
397 | kw("context"), context,
398 | kw("source-crs"), sourceCrs,
399 | kw("target-crs"), targetCrs
400 | ));
401 | }
402 |
403 | /**
404 | * Create a transformation between two CRS objects using default context.
405 | * @param sourceCrs source CRS object
406 | * @param targetCrs target CRS object
407 | * @return transformation object
408 | */
409 | public static Object createCrsToCrsFromPj(Object sourceCrs, Object targetCrs) {
410 | if (createCrsToCrsFromPjFn == null) createCrsToCrsFromPjFn = getVar("proj-create-crs-to-crs-from-pj");
411 | return createCrsToCrsFromPjFn.invoke(map(
412 | kw("source-crs"), sourceCrs,
413 | kw("target-crs"), targetCrs
414 | ));
415 | }
416 |
417 | /**
418 | * Create a CRS object from the database by authority and code.
419 | * @param context the PROJ context
420 | * @param authName authority name (e.g., "EPSG")
421 | * @param code the code (e.g., "4326")
422 | * @return CRS object (PJ pointer)
423 | */
424 | public static Object createFromDatabase(Object context, String authName, String code) {
425 | if (createFromDatabaseFn == null) createFromDatabaseFn = getVar("proj-create-from-database");
426 | return createFromDatabaseFn.invoke(map(
427 | kw("context"), context,
428 | kw("auth-name"), authName,
429 | kw("code"), code,
430 | kw("category"), PJ_CATEGORY_CRS
431 | ));
432 | }
433 |
434 | /**
435 | * Create a CRS object from the database using default context.
436 | * @param authName authority name (e.g., "EPSG")
437 | * @param code the code (e.g., "4326")
438 | * @return CRS object (PJ pointer)
439 | */
440 | public static Object createFromDatabase(String authName, String code) {
441 | if (createFromDatabaseFn == null) createFromDatabaseFn = getVar("proj-create-from-database");
442 | return createFromDatabaseFn.invoke(map(
443 | kw("auth-name"), authName,
444 | kw("code"), code,
445 | kw("category"), PJ_CATEGORY_CRS
446 | ));
447 | }
448 |
449 | /**
450 | * Transform an array of coordinates.
451 | * @param transformation the transformation object
452 | * @param coordArray the coordinate array (modified in place)
453 | * @param n number of coordinates to transform
454 | * @return 0 on success, error code on failure
455 | */
456 | public static int transArray(Object transformation, Object coordArray, int n) {
457 | return transArray(transformation, coordArray, n, 1); // PJ_FWD = 1
458 | }
459 |
460 | /**
461 | * Transform an array of coordinates with specified direction.
462 | * @param transformation the transformation object
463 | * @param coordArray the coordinate array (modified in place)
464 | * @param n number of coordinates to transform
465 | * @param direction transformation direction (1=forward, -1=inverse, 0=identity)
466 | * @return 0 on success, error code on failure
467 | */
468 | public static int transArray(Object transformation, Object coordArray, int n, int direction) {
469 | if (transArrayFn == null) transArrayFn = getVar("proj-trans-array");
470 | Object result = transArrayFn.invoke(map(
471 | kw("p"), transformation,
472 | kw("coord"), coordArray,
473 | kw("n"), n,
474 | kw("direction"), direction
475 | ));
476 | return result != null ? ((Number) result).intValue() : 0;
477 | }
478 |
479 | /**
480 | * Get list of available authorities from the PROJ database.
481 | * @param context the PROJ context
482 | * @return list of authority names (e.g., ["EPSG", "ESRI", "PROJ"])
483 | */
484 | @SuppressWarnings("unchecked")
485 | public static List