Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/thi-ng/geom

2D/3D geometry toolkit for Clojure/Clojurescript
https://github.com/thi-ng/geom

charts geometry mesh-generation obj opengl ply stl subdivision svg visualization voxel webgl

Last synced: 5 months ago
JSON representation

2D/3D geometry toolkit for Clojure/Clojurescript

Awesome Lists containing this project

README 

          
#+SETUPFILE: ./meta/setup.org

#+TITLE: thi.ng/geom



[[./assets/voxel/svo-d7.jpg]]



* Contents                                                         :toc_3_gh:

 - [[#about-the-project][About the project]]

     - [[#status][Status]]

     - [[#leiningen-coordinates][Leiningen coordinates]]

         - [[#latest-snapshot][Latest snapshot]]

         - [[#latest-stable][Latest stable]]

         - [[#additional-dependencies-for-jogl][Additional dependencies for JOGL]]

     - [[#overview][Overview]]

         - [[#example-usage][Example usage]]

         - [[#project-structure][Project structure]]

         - [[#main-features-non-exhaustive-list][Main features (non-exhaustive list)]]

         - [[#api-scope][API scope]]

     - [[#project-structure][Project structure]]

         - [[#core][core]]

         - [[#types][types]]

         - [[#utils][utils]]

         - [[#mesh][mesh]]

         - [[#physics][physics]]

         - [[#svg][svg]]

         - [[#viz][viz]]

         - [[#voxel][voxel]]

         - [[#opengl--webgl][OpenGL & WebGL]]

     - [[#release-history--changelog][Release history & changelog]]

     - [[#contributors][Contributors]]

     - [[#license][License]]



* About the project



** Status



The project was in active, almost daily development from late 2011 - summer 2016

during its 4th iteration/rewrite cycle. Originally developed in a Literate

Programming style using Emacs & Org-mode, in May 2018 it was decided to revert

to a traditional Clojure project setup to encourage more contributions from

other interested parties. The original .org source files are kept for reference

in the [[./org/]] directory until further notice.



Regardless of version number, the library is mature and has been used

successfully in several commercial projects over the past 10 years and can be

considered stable for most use cases.



** Leiningen coordinates



#+BEGIN_SRC clojure

  [thi.ng/geom "1.0.1"]

#+END_SRC



*** Additional dependencies for JOGL



If you're intending to use this library's OpenGL functionality under

Clojure (not ClojureScript), the following additional native

dependencies must be added to your project (for each platform you

intend to use):



#+BEGIN_SRC clojure

[org.jogamp.gluegen/gluegen-rt "2.3.2" :classifier "natives-macosx-universal"]

[org.jogamp.jogl/jogl-all "2.3.2" :classifier "natives-macosx-universal"]

#+END_SRC



The full list of supported platform =:classifier='s:



| natives-android-aarch64.jar  |

| natives-android-armv6.jar    |

| natives-linux-amd64.jar      |

| natives-linux-armv6.jar      |

| natives-linux-armv6hf.jar    |

| natives-linux-i586.jar       |

| natives-macosx-universal.jar |

| natives-solaris-amd64.jar    |

| natives-solaris-i586.jar     |

| natives-windows-amd64.jar    |

| natives-windows-i586.jar     |



** Overview



thi.ng/geom is a comprehensive and modular geometry & visualization

toolkit for Clojure/ClojureScript. It provides a large set of purely

math & geometry oriented data types, a polymorphic, largely protocol

based API to transform/convert types and various ways to create

interactive visualizations in SVG, WebGL, OpenGL, both in the browser

and in desktop environments.



Embracing Clojure's approach of data transformations, the library's

core philosophy is based on a functional approach to generative design

tasks with hundreds of hours spent on refining & optimizing the core

API for both Clojure & Clojurescript.



Unlike most other open source projects, this project has been

developed in a literate programming style and has been in active,

regular development since late 2011, currently in its 4th

iteration/rewrite cycle.



*You're highly encouraged to consult the source code, which contains

documentation, examples, diagrams and general usage pattern hints.*



This project is part of the [[https://github.com/thi-ng/][thi.ng]] collection of Clojure &

Clojurescript libraries and makes uses of several other projects in

this collection (see dependencies further below).



*** Example usage



A growing number (currently ~40) of small examples are included in

this repo under the =/examples= directory:



- [[./org/examples/gl/jogl.org][OpenGL demos]] (Clojure)

- [[./org/examples/gl/webgl.org][WebGL demos]] (Clojurescript + links to live versions)

- [[./org/examples/svg/demos.org][SVG examples]] (incl. 3D rendered meshes in SVG)

- [[./org/examples/viz/demos.org][Visualization examples]] (charts, heatmaps, timelines etc.)

- [[./org/examples/ptf/demos.org][PTF mesh examples]] (mesh skinning & Luxrender)

- [[./org/examples/voxel/demos.org][Voxel examples]] (isosurface extraction from volumetric data)



Interactive examples:



- [[http://dev.thi.ng/gradients/][Procedural Color Gradient designer]]

- [[http://demo.thi.ng/geom/physics/strands.html][SVG physics strands]]

- [[http://demo.thi.ng/ws-ldn-5/][WebGL workshop teaser]]

- [[http://demo.thi.ng/sjo/][WebGL workshop example]] (early game prototype)



Growing list of [[http://workshop.thi.ng/][thi.ng workshop]] repositories (These workshops were

running on a monthly basis & internationally in 2015/2016):



- [[http://thi.ng/ws-ldn-1][WS-LDN-1]]

- [[http://thi.ng/ws-ldn-2][WS-LDN-2]]

- [[http://thi.ng/ws-bln-1][WS-BLN-1]]

- WS-LDN-5 (WebGL, source code forthcoming)

- WS-LDN-6 (Desktop apps, OpenGL/WebGL, source code forthcoming)

- [[http://thi.ng/ws-ldn-8][WS-LDN-8]] (WebGL, WebRTC, Web workers, asm.js)



A preliminary list of other projects using this library:



- [[https://medium.com/@thi.ng/evolutionary-failures-part-1-54522c69be37][HOLO Magazine cover & guest design]]

- [[https://github.com/postspectacular/devart-codefactory/][Google DevArt Co(de)Factory]]

- [[https://github.com/jackrusher/geometer/][Geometer]] (by [[https://github.com/jackrusher][Jack Rusher]])

- [[http://holiday2014.movingbrands.com][MB Home installation]]

- [[http://github.com/learn-postspectacular/resonate-workshop-2015][Resonate 2015 workshop]]

- [[https://github.com/learn-postspectacular/resonate-workshop-2014][Resonate 2014 workshop]]

- [[http://github.com/thi-ng/luxor][thi.ng/luxor]]

- [[http://github.com/thi-ng/morphogen][thi.ng/morphogen]]

- [[http://thi.ng/][thi.ng website]]



*** Project structure



Use the diagram below to quickly navigate to any namespace in the

project. Nodes in the graph have tooltips with a brief description of

each namespace. *Note:* Due to GH restrictions on SVG files, first

click anywhere on the diagram before trying to navigate to a specific

namespace.



[[./assets/overview.svg]]



*** Main features (non-exhaustive list)



- Comprehensive & optimized 2D/3D vector & matrix algebra / transformations

- Custom, optimized vector types w/ GLSL style vector swizzling & full

  Clojure sequence API support

- Unified, easy-to-learn & extensible core API defined via ~50 polymorphic protocols

- Unified OpenGL (v3.3+) & WebGL abstractions of common features,

  shader, buffer & texture utilities

- Declarative GLSL shader specs and code generation

- Optional OpenGL/WebGL shader presets based on [[http://thi.ng/shadergraph][thi.ng/shadergraph]]

- Declarative OpenGL/WebGL FBO-based multi-pass shader pipeline

  creation & execution tools

- OpenGL helpers for desktop apps (wrapping [[http://jogamp.org/jogl][JOGL]])

- React.js component helpers for WebGL

- 3D SVG mesh renderer with software facet shader support

- SVG generation API & optional conversion of geom types

- Declararitve 2D data visualization module with various modes (area,

  bar, line, scatter, contours, stacks etc., cartesian/polar axes)

- 35+ custom (mainly immutable) geometry types implementing core protocols

- Shape analysis (surface area, circumference, distance & volume

  calculations) for all implemented types

- 2D/3D intersection & classification checks (vs. point, line, ray, shapes)

- Access entities as graph-like structures (vertices/edges)

- 2D/3D platonic entity to 3D polygon mesh conversion (w/ many options)

- Optimized conversions to OpenGL/WebGL (with attributes, indexed, non-indexed)

- Flexible & customizable mesh vertex attribute generators

- Subdivision meshes (Catmull-Clark, Doo-Sabin, Butterfly)

- Parallel-transport frame sweep mesh generation from point sequences

  (skinning with arbitrary profiles, incl. profile morphing)

- 3D Lathe meshes from 2D curves

- 2D shape extrusions as 3D mesh (solid or walled)

- Delaunay triangulation of 2D point clouds

- Tesselation of simple 2D polygons (no holes)

- Basic SVG == parsing with different segment types

- Basic insetting of simple 2D polygons (no miter support)

- Shape subdivision (only lines, triangles, rects, quads, tetrahedrons)

- Shape boundary sampling (at fixed resolution or uniform distance)

- Sutherland-Hodgeman clipping of 2D polygons

- 3D Boolean (CSG) operations on meshes (union, difference, intersection)

- 3D geometry export (PLY, STL, OBJ, OFF formats)

- 3D mesh repair tools (T-junctions, unify vertices etc.)

- 2D/3D particle based Verlet Physics with customizable behaviors & constraints

- 2D convex hull

- 2D/3D quadtree/octree (mutable) for fast spatial indexing

- Automatic curve generation from point seqs (cubic, Chaikin etc.)

- Unfolding of 3D meshes to 2D (WIP) for digital fabrication

...



*** API scope



Since the core library does only deal with pure "platonic" geometry

types, it doesn't directly address any display or rendering

functionality at all. However a number of support modules are

provided, incl. OpenGL 3/4, WebGL & SVG support, to allow visualizing

results and/or exporting generated assets. 2D/3D shape/mesh exporters

are provided as well and together with sister libraries like

[[https://github.com/thi-ng/luxor][thi.ng/luxor]], it's also possible to generate complete 3D scenes for

high quality & high resolution non-realtime rendering using [[https://github.com/LuxRender][Luxrender]] now [[https://luxcorerender.org/][LuxCoreRender]].



Furthermore, providing all functionality under a common API for both

Clojure & Clojurescript, makes it trivial to offload heavy operations

(e.g. large mesh processing) to the server side.



** Project structure

*** core



[[./src/thi/ng/geom/][source]]



These namespaces define the core functionality of this library,

including the approx. 50 protocols and implementations of fundamental

geometry types/functions like 2d/3d vector algebra, matrices,

quaternion (+ related convenience constructors & conversions)



*** types



[[./src/thi/ng/geom/][source]]



This directory contains all high-level 2d/3d data types with their

implementations of the various core protocols. From a user

perspective, these namespaces defined here provide most of this

project's core functionality.



*** utils



[[./src/thi/ng/geom/utils/][source]]



A number of often needed utility functions to deal with point

collections, normals, path sampling, triangle properties etc. Also

included here are shape intersection tests, curve subdivisions and 2D

Delaunay triangulation.



*** mesh



[[./src/thi/ng/geom/mesh/][source]]



Several tools & operations related to working with 3d meshes, incl.

I/O, subdivisions, repair / cleaning, CSG / Boolean mesh merge,

mesh generators (polyhedra, lathe etc.)



*** physics



[[./src/thi/ng/geom/physics/][source]]



This module provides a simple 2d/3d particle-based physics engine with

Verlet integration and support for custom behaviors and constaints,

both for individual particles and global. Particles can be connected

with springs of varying stiffness as well as made interdependent using

positive or negative force fields (attractors).



*** svg



[[./src/thi/ng/geom/svg/][source]]



A module to help with building SVG based visualizations of geom

entities using hiccup compatible syntax. Includes a customizable 3D

mesh renderer w/ software shader support.



*** viz



[[./src/thi/ng/geom/viz/][source]]



Declarative, highly customizable 2D data visualization module with ~10

different layout methods, 3 axis types, cartesian and polar domain

support. Currently SVG only, but planned to be format-independent.



*** voxel



[[./src/thi/ng/geom/voxel/][source]]



An experimental implementation of a in-memory sparse voxel tree (SVO)

and related functionality to extract isosurface polygon meshes from

the tree.



*** OpenGL & WebGL



[[./src/thi/ng/geom/gl/][source]]



This module provides a unified API to common OpenGL/WebGL

functionality (context creation, shader management & presets, buffer

management, textures, FBO etc.), as well as a number of optimized mesh

types, conversion & rendering functions, cameras etc. to simplify the

use of other geometry types defined in this project with OpenGL, both on

the desktop and in the browser. The Clojure version wraps JOGL.



** Release history & changelog



See [[./CHANGELOG.org][CHANGELOG.org]] for further details.



| *Version* | *Released* | *Lein coordinates*          | *Tagged Github URL*                                          |

|-----------+------------+-----------------------------+--------------------------------------------------------------|

| 1.0.1     | 2023-10-23 | =[thi.ng/geom "1.0.1"]=     | [[https://github.com/thi-ng/geom/tree/1.0.1][1.0.1]]         |

| 1.0.0     | 2023-01-22 | =[thi.ng/geom "1.0.0"]=     | [[https://github.com/thi-ng/geom/tree/1.0.0][1.0.0]]         |

| 1.0.0-RC5 | 2022-04-23 | =[thi.ng/geom "1.0.0-RC5"]= | [[https://github.com/thi-ng/geom/tree/1.0.0-RC5][1.0.0-RC5]] |

| 1.0.0-RC4 | 2019-10-07 | =[thi.ng/geom "1.0.0-RC4"]= | [[https://github.com/thi-ng/geom/tree/1.0.0-RC4][1.0.0-RC4]] |

| 1.0.0-RC3 | 2018-06-01 | =[thi.ng/geom "1.0.0-RC3"]= | [[https://github.com/thi-ng/geom/tree/1.0.0-RC3][1.0.0-RC3]] |

| 1.0.0-RC2 | 2018-06-01 | =[thi.ng/geom "1.0.0-RC2"]= | [[https://github.com/thi-ng/geom/tree/1.0.0-RC2][1.0.0-RC2]] |

| 1.0.0-RC1 | 2018-05-31 | =[thi.ng/geom "1.0.0-RC1"]= | [[https://github.com/thi-ng/geom/tree/1.0.0-RC1][1.0.0-RC1]] |

|   0.0.908 | 2015-11-08 | =[thi.ng/geom "0.0.908"]=   | [[https://github.com/thi-ng/geom/tree/r908][r908]]           |

|   0.0.881 | 2015-06-21 | =[thi.ng/geom "0.0.881"]=   | [[https://github.com/thi-ng/geom/tree/r881][r881]]           |

|   0.0.859 | 2015-06-15 | =[thi.ng/geom "0.0.859"]=   | [[https://github.com/thi-ng/geom/tree/r856][r859]]           |

|   0.0.856 | 2015-06-14 | =[thi.ng/geom "0.0.856"]=   | [[https://github.com/thi-ng/geom/tree/r856][r856]]           |

|   0.0.815 | 2015-06-01 | =[thi.ng/geom "0.0.815"]=   | [[https://github.com/thi-ng/geom/tree/r815][r815]]           |

|   0.0.803 | 2015-05-26 | =[thi.ng/geom "0.0.803"]=   | [[https://github.com/thi-ng/geom/tree/r803][r803]]           |

|   0.0.783 | 2015-04-27 | =[thi.ng/geom "0.0.783"]=   | [[https://github.com/thi-ng/geom/tree/r783][r783]]           |

|   0.0.770 | 2015-03-29 | =[thi.ng/geom "0.0.770"]=   | [[https://github.com/thi-ng/geom/tree/r770][r770]]           |

|   0.0.743 | 2015-03-23 | =[thi.ng/geom "0.0.743"]=   | [[https://github.com/thi-ng/geom/tree/r743][r743]]           |

|   0.0.737 | 2015-03-22 | =[thi.ng/geom "0.0.737"]=   | [[https://github.com/thi-ng/geom/tree/r737][r737]]           |

|   0.0-725 | 2015-03-15 | =[thi.ng/geom "0.0-725"]=   | [[https://github.com/thi-ng/geom/tree/r725][r725]]           |

|   0.0-715 | 2015-02-25 | =[thi.ng/geom "0.0-715"]=   | [[https://github.com/thi-ng/geom/tree/r715][r715]]           |

|   0.0-709 | 2015-02-22 | =[thi.ng/geom "0.0-709"]=   | [[https://github.com/thi-ng/geom/tree/r709][r709]]           |

|     0.2.0 | 2014-03-10 | =[thi.ng/geom "0.2.0"]=     | [[https://github.com/thi-ng/geom/tree/0.2.0][0.2.0]]         |



** Contributors



- [[https://github.com/postspectacular][@postspectacular]]

- [[https://github.com/vl4dimir][@vl4dimir]]

- [[https://github.com/skrat][@skrat]]

- [[https://github.com/acron0][@acron0]]

- [[https://github.com/arichiardi][@arichiardi]]

- [[https://github.com/Rovanion][@Rovanion]]

- [[https://github.com/reitzensteinm][@reitzensteinm]]

- [[https://github.com/stwind][@stwind]]

- [[https://github.com/fdb][@fdb]]

- [[https://github.com/jgmize][@jgmize]]

- [[https://github.com/dimovich][@dimovich]]



** License



(c) 2013 - 2023 Karsten Schmidt



This project is open source and licensed under the [[http://www.apache.org/licenses/LICENSE-2.0][Apache Software License 2.0]].