3D Model Library

7.7

top ← prev up next →

3D Model Library

1 Introduction

This library is used to represent 3 dimensional data as vertices and polygons (or polys in short) and also auxilary data such as materials and uvmaps.

This kind of representation is used fairly common among videogames and the like. It is also used among most standard 3D model formats.

2 Getting Started

Install this library using planet or put it in racket staticlly. Then see the function new-model to start generating model data.

A model is a container of meshes. The meshes contain the actual data.

A mesh has a name aswell some amount of vertices, uv-cooridantes and polygons, also an optional origin vector to be used for movement calculations. Each mesh must have a unique name.

At this time hierachry is not supported, all meshes are linearly stored.

Vertices and uv-coordiantes are referenced by polygons. They can be refernced by multiple polygons. New ones can be inserted without having to be referenced by a polygons. However it is the programmers responsibility to ensure that polygons that have elements removed recive proper substitutes.

This library also provides some primitive geometric manipulative functions, but these are not optimized and thus unsuable for realtime or large scale data processing. OpenGL support has been dileberatly omited to keep the library simple.

3 Reference

procedure
(new-model name) → mpair?
name : (string?)

This function generates a new model object with a name, that stores meshes.

A model’s actuall data is organized into and stored inside meshes.

procedure
(add-mesh! model name [vertices uvs polys]) → mesh?
  model : (mpair?)
  name : (string?)
  vertices : (list?) = '()
  uvs : (list?) = '()
  polys : (list?) = '()

Add a new mesh with a name to a model.

A mesh is the basic data container for 3 dimensional data.

Each mesh must have a unique name.

Can optionally be initialised with data, a list of verices, a list of uvmaps and a list of polys.

Returns the new mesh.

procedure
(mesh? mesh) → boolean?
mesh : (any/c?)

Checks if a object represents a valid mesh.

procedure
(get-mesh model name) → (or/c mesh? boolean?)
model : (mpair?)
name : (string?)

Gets a mesh by name from a model.

procedure
(get-mesh-name mesh) → string?
mesh : (mesh?)

Gets the name of a mesh.

procedure
(rename-mesh! mesh name) → void?
mesh : (mesh?)
name : (string?)

Renames a mesh.

procedure
(delete-mesh! model mesh) → void?
model : (mpair?)
mesh : (mesh?)

Deletes a mesh from a model.

procedure
(join-meshes! model mesh1 mesh2) → void?
  model : (mpair?)
  mesh1 : (mesh?)
  mesh2 : (mesh?)

Joins mesh2 into mesh1. This deletes mesh2 afterwards.

procedure
(get-vertices mesh) → list?
mesh : (mesh?)

Gets list of the vertices of a mesh.

procedure
(add-vertex! mesh x y z) → void?
  mesh : (mesh?)
  x : (number?)
  y : (number?)
  z : (number?)

Adds a single point in space with the x y z coordinates.

procedure
(delete-vertex! mesh vertex) → void?
mesh : (mesh?)
vertex : (vector?)

Deletes a vertex from a mesh.

procedure
(get-polys mesh) → list?
mesh : (mesh?)

Gets list of the polys of a mesh.

procedure
(add-poly! mesh [vertices uvs material origin]) → void?
  mesh : (mesh?)
  vertices : (list?) = ()
  uvs : (list?) = ()
  material : (string?) = ""
  origin : (vector?) = #(0 0 0)

Adds a poly to a mesh consisting with optional vertex and the uv cooridante references aswell as a material and origin.

procedure
(delete-poly! mesh poly) → void?
mesh : (mesh?)
poly : (vector?)

Deletes a poly from a mesh.

This function does not remove referenced vertices or uv-coordinates.

procedure
(get-poly-vertices mesh poly) → list?
mesh : (mesh?)
poly : (vector?)

Gets a list the vertices of a poly.

procedure
(get-uvmap mesh) → list?
mesh : (mesh?)

Gets a list the uv cooridnates of a mesh.

procedure
(add-uv! mesh x y z) → void?
  mesh : (mesh?)
  x : (number?)
  y : (number?)
  z : (number?)

Add uv coordinate to a mesh.

procedure
(delete-uv! mesh uv) → void?
mesh : (mesh?)
uv : (vector?)

Deletes a uv coordinate from a mesh.

procedure
(get-origin mesh) → vector?
mesh : (mesh?)

Get origin point of a mesh.

This defines the pivot point in rotations and for mirroring.

procedure
(set-origin! mesh x y z) → vector?
  mesh : (mesh?)
  x : (number?)
  y : (number?)
  z : (number?)

Set origin point of a mesh.

procedure
(translate-vertex! vertex
x-offset
y-offset
z-offset) → void?
  vertex : (vector?)
  x-offset : (number?)
  y-offset : (number?)
  z-offset : (number?)

Translate (move) a vertex by the given x y z offsets.

procedure
(rotate-vertex! vertex xy yz zx origin) → void?
  vertex : (vector?)
  xy : (number?)
  yz : (number?)
  zx : (number?)
  origin : (vector?)

Rotate a vertex clockwise around origin.

Rotation for each axis is specified by a floating number between 0 and 1, where 0 is no rotation and 1 would be one whole rotation. 0.5 would be a rotation of 180 degrees. Numbers larger or equal than 1 will be wraped round.

Rotation is performed along 2 axis, you can choose any 2 axis. Subsequent roatation along an axis 2 time will be complementary.

Caution: due to impercision in the representation subsequent rotation of large object may lead to significantly deformed results.

procedure
(scale-vertex! vertex x y z) → void?
  vertex : (vector?)
  x : (number?)
  y : (number?)
  z : (number?)

Scales a vertex some amount along any axis.

procedure
(mirror-vertex! vertex
x-axis
y-axis
z-axis
origin) → void?
  vertex : (vector?)
  x-axis : (boolean?)
  y-axis : (boolean?)
  z-axis : (boolean?)
  origin : (vector?)

Mirror a vertex at any of its axis relative to give origin.

Origin is a vector of 3 numbers, each describing the axis around which the mirroring should happen.

Set any of the cooridnate arguments to true to perform a mirroring on corresponding axis.

procedure
(translate-mesh! mesh
x-offset
y-offset
z-offset) → void?
  mesh : (mesh?)
  x-offset : (number?)
  y-offset : (number?)
  z-offset : (number?)

Translate (move) a mesh by the given x y z offsets.

Origin will be affected aswell.

procedure
(rotate-mesh! mesh xy yz zx) → void?
  mesh : (mesh?)
  xy : (number?)
  yz : (number?)
  zx : (number?)

Rotate a mesh clockwise around origin.

Rotation is performed along 2 axis, you can choose any 2 axis. Subsequent roatation along an axis 2 time will be complementary.

Caution: due to impercision in the representation subsequent rotation of large object may lead to significantly deformed results.

procedure
(scale-mesh! mesh x y z) → void?
  mesh : (mesh?)
  x : (number?)
  y : (number?)
  z : (number?)

Scales a mesh some amount along any axis.

procedure
(mirror-mesh! mesh x-axis y-axis z-axis) → void?
  mesh : (mesh?)
  x-axis : (boolean?)
  y-axis : (boolean?)
  z-axis : (boolean?)

Mirror a mesh at any of its axis relative to its origin.

Set any of the cooridnate arguments to true to perform a mirroring of corresponding axis.

4 Copyright and contact

Writen by "Code_Man". Send feedback to Code_Man at Cybnet.ch. See code_man.cybnet.ch for more stuff of mine.

Licenced under MIT X11.

No implied warranties or liability of any kind, use at own risk.

top ← prev up next →

1	Introduction
2	Getting Started
3	Reference
4	Copyright and contact