/VoxelGeometry

Voxel geometry structure generator

Primary LanguageTypeScriptGNU Affero General Public License v3.0AGPL-3.0

Voxel Geometry

logo

Voxel Geometry is voxel geometry library which is used to construct Space (A collection of 3-dimension Vectors) and perform transformation between Spaces.

A voxel represents a value on a regular grid in three-dimensional space. Geometry means this software is very mathematically and owns more features as follows for generating awesome structures.

  • Basic Geometry : Sphere, circle, cylinder, torus, line and more.
  • Lindenmayer system (L-System) : A parallel rewriting system. The recursive nature of the L-system rules leads to self-similarity and thereby, fractal-like forms are easy to describe with an L-system.
  • Turtle Graphic : Full features and extensions of turtle graphics.
  • Transformer : Transforming space into another by pipe, compose, scale, diffusion and more.
  • Expression drawing : Constructing from math expression or parametric equation.
  • Canvas API : Javascript browser graphics API support.
  • Linear and Nonlinear Transform : Mapping space into another one.
  • Diffusion Limited Aggression : Simulating particles undergoing a random walk due to Brownian motion cluster together to form aggregates of such particles.
  • Chaos Theory : Iterated Function System which uses Chaos Game.

Application

You can check the branches for the Application of this library in Minecraft.

  • core : Voxel Geometry core
  • ws : Voxel Geometry for Minecraft Bedrock (Based on Websocket server)
  • gt : Voxel Geometry for Minecraft Bedrock (Based on Gametest framework)
  • webviewer : Voxel Geometry Web Viewer

Screenshots

Check the gallery folder for more information.

Installation

npm i @pureeval/voxel-geometry

Basic Concepts

Vector

A vector represent a voxel in the Space, which has 3 components.

// Create a unit vector
const vec: Vec3 = vec3(1, 1, 1);

Space

Many Voxel Geometry functions will return a Space (A array of 3D vectors).

const ball: Space = sphere(5, 4);

Basic Geometry

Sphere

Create a sphere with radius.

sphere :: (radius, inner_radius) -> Space
sphere(5,4)

Circle

Create a circle with radius.

circle :: (radius, inner_radius) -> Space
circle(5, 4)

Torus

Create a torus.

torus :: (radius, ring_radius) -> Space
torus(10,8)

Transformer

scale

Scale up a Space

scale :: (Space, size) -> Space

swap

Change the direction of a space.

swap :: (Space, number, number) -> Space

pipe

Take the point of the previous space as the origin of the next space.

pipe :: (Space_1, Space_2, ...) -> Space

diffusion

Spread out points of a space by a factor.

diffusion :: (Space, factor) -> Space

move

Move a space into a specific point.

move :: (Space, x, y, z) -> Space

embed

Embed a space into another space

embed :: (Space, Space) -> Space

Array Generator

Construct a discrete set of points.

array_gen :: (xn, yn, zn, dx, dy, dz) -> Space
  • _n : Count
  • d_ : Interval

With step function:

array_gen_fn :: (xn, yn, zn, num -> num, num -> num, num -> num) -> Space

Turtle

Turtle2D

Turtle graphics are vector graphics using a relative cursor (the "turtle") upon a Cartesian plane (x and y axis).

Voxel Geometry supports basic functions of turtle graphics:

// Draw a straight with length 10
const t = new Turtle2D();
t.forward(10);
plot(t.getTrack());

Turtle3D

Same as Turtle2D but lives in 3D space.

L-System

An L-system or Lindenmayer system is a parallel rewriting system and a type of formal grammar.It consists of an alphabet, a collection of production rules that expand each symbol into some larger string of symbols, an initial "axiom" string from which to begin construction, and a mechanism (Such as Turtle Graphics) for translating the generated strings into geometric structures.

In Voxel Geometry, you can use this function to create a Bracketed L-system:

lsystem :: (axiom, Rules, generation) -> Space

For instance, we can create Peano curve by using l-system.

lsystem(
	'X',
	{
		X: 'XFYFX+F+YFXFY-F-XFYFX',
		Y: 'YFXFY-F-XFYFX+F+YFXFY'
	},
	5
);

Voxel Geometry uses Turtle Graphics as default mechanism.

Canvas

Voxel geometry supports a part of Canvas API in browser.

Math Interpreter

Parametric Equation

Parametric equations are commonly used to express the coordinates of the points that make up a geometric object such as a curve or surface. It includes group of quantities as functions of one or more independent variables called parameters.

For instance, we could write down the Parametric equations of ellipse. (t is the parameter, which varies from 0 to 2*Pi)

// a and b are constants
x = a * cos(t);
y = b * sin(t);

Express this in Voxel Geometry (step represent the changing value of the parameter):

let step = 0.1;
plot(simple_parametric('5*Math.cos(t)', '0', '10*Math.sin(t)', ['t', 0, Math.PI * 2, step]));

Expression

Takes a math expression (Such as inequality) as a condition and intervals, construct a space satisfies this:

simple_equation :: (Expr, start, end, step) -> Space

For instance we can construct a sphere:

plot(simple_equation('x*x+y*y+z*z<=5', -5, 5, 1));

Diffusion Limited Aggression

Simulating particles undergoing a random walk due to Brownian motion cluster together to form aggregates of such particles.

DLA2D

DLA2D :: (width, maxWalk, iterations, stepLength, temperature, stuckSpace = centerPoint) -> Space
  • width : Width of operation space.
  • maxWalk : Maximum number of particles that can exist simultaneously.
  • iterations : Determine how many times before each particle supplement.
  • stepLength : Step size of particles.
  • temperature : The temperature of the iterative system will gradually decrease, which is related to the number of subsequent replenishment points.
  • stuckSpace : A collection of particles that have been fixed at the beginning.

DLA3D

Same as DLA2D but lives in 3D space.

DLA3D :: (width, maxWalk, iterations, stepLength, temperature, stuckSpace = centerPoint) -> Space

Iterated Function System

An iterated function system is a finite set of mappings on a complete metric space. Iterated function systems (IFSs) are a method of constructing fractals.

Voxel Geometry uses the classic algorithm named Chaos Game to compute IFS fractals.

Voxel Geometry uses the representation introduced in this website

By convention an IFS is written in rows of numbers in the form :

a    b    c    d    e    f    p

which describes the transform λ(x,y).(ax+by+e,cx+dy+f). The value p represents the percentage of the fractal's area generated by the transform. Theoretically it is not required but if you select it well, the fractal is drawn much more efficiently.

create_IFS :: (form, width, height) -> IFS

Here is a classic to try:

// Create an IFS with Fractals.angle, 100000 iteration
plot(create_IFS(Fractals.angle, 100, 100).run(100000));