Introduction
pycg3d - a pure Python package for Computational Geometry in 3D.
Requirements:
- CPython 2.7+, CPython 3.3+ or pypy 4.0+
Highlights:
- Pure Python
- Minimal dependency
- Friendly operators for building expressions(e.g. ’+’, ’-’, ’*’ and ’^’ operators for vectors)
- No graphics
Features:
- Classes for modeling geometrical/mathematical objects like Point, Vector, Line, Plane in 3D space;
- Built-in functions and operators: e.g. addition, subtraction, dot product, cross product for Vector;
- Classes for modeling transformations like translation, rotation, reflection etc, which could be chained and applied to Point
- Utility functions
Installation:
$ git clone https://github.com/simright/pycg3d.git
$ cd pycg3d
$ python setup.py install
or
$ pip install pycg3d
User Guide
pycg3d provides classes for modeling Point, Vector, Line, Plane and Transformation in 3D space, and all functions are provided via the instances of these classes.
Vector
Create a vector and access its components:
from pycg3d.cg3d_vector import CG3dVector
v1 = CG3dVector(1.0, 0.0, 0.0)
print v1[0], v1[1], v1[2] # 1.0 0.0 0.0
v1[1]=2.0
print v1 # [1.0, 2.0, 0.0]
Use operators ’+’/’-’ for component-wise addition/subtraction of vectors:
from pycg3d.cg3d_vector import CG3dVector
v1 = CG3dVector(1.0, 2.0, 3.0)
v2 = CG3dVector(1.0, 0.0, 2.0)
v3 = v1 + v2 # v3 == CG3dVector(2.0, 2.0, 5.0)
v4 = v1 - v2 # v4 == CG3dVector(0.0, 2.0, 1.0)
Use operator ’*’ for dot product of vectors:
from pycg3d.cg3d_vector import CG3dVector
va = CG3dVector(1.0, 0.0, 0.0)
vb = CG3dVector(2.0, 2.0, 0.0)
dp = va*vb # 2.0
Use operator ’^’ for cross product of vectors
from pycg3d.cg3d_vector import CG3dVector
vx = CG3dVector(1.0, 0.0, 0.0)
vy = CG3dVector(0.0, 1.0, 0.0)
vz = vx^vy # vz == CG3dVector(0.0, 0.0, 1.0)
Class CG3dVector defines a vector in 3D space.
Point
Class CG3dPoint is actually an alias of class CG3dVector.
from pycg3d.cg3d_vector import CG3dVector
from pycg3d.cg3d_point import CG3dPoint
p1 = CG3dPoint(1.0, 0.0, 0.0)
print isinstance(p1, CG3dVector) # True
Class CG3dPoint defines a point in 3D space, and it is actually an alias of class CG3dVector.
Line
Class CG3dLine2P defines a line with two points:
from pycg3d.cg3d_point import CG3dPoint
from pycg3d.cg3d_line import CG3dLine2P
p1 = CG3dPoint(1.0, 0.0, 0.0)
p2 = CG3dPoint(0.0, 1.0, 0.0)
line = CG3dLine2P(p1, p2)
- Class CG3dLine is the super/base class for any class that defines a line in 3D space.
- pycg3d provides various subclasses for defining Line in different ways, e.g.
- Class CG3dLine2P : define a Line by two points
- The instances of these subclasses could be used equally wherever requires a Line as input.
Plane
Define a plane by a point and normal vector:
from pycg3d.cg3d_point import CG3dPoint
from pycg3d.cg3d_point import CG3dVector
from pycg3d.cg3d_plane import CG3dPlanePN
yz_plane = CG3dPlanePN(CG3dPoint(0.0, 0.0, 0.0), CG3dVector(1.0, 0.0, 0.0))
Define a plane by three points:
from pycg3d.cg3d_point import CG3dPoint
from pycg3d.cg3d_plane import CG3dPlane3P
xy_plane = CG3dPlane3P(
CG3dPoint(0.0, 0.0, 0.0),
CG3dPoint(1.0, 0.0, 0.0),
CG3dPoint(0.0, 1.0, 0.0)
)
- Class CG3dPlane is the super/base class for any class that defines a Plane in 3D space.
- pycg3d provides various subclasses for defining a Plane in different ways, e.g.
- Class CG3dPlane3P: define a plane with 3 points in the plane
- Class CG3dPlanePN: defines a plane with a point in the plane and a normal vector
- The instances of these subclasses could be used equally wherever requires a Plane as input.
Transformation
- Transformation (translation, rotation, reflection etc) can be applied to a Point in 3D space, and returns a new Point;
- Class CG3dTransformer is the super/base class for any class that defines a Transformation in 3D space.
- pycg3d provides various subclasses for defining Transformation in different ways. The instances of these subclasses could be used wherever requires a Transformation as input.
Translation
Translation:
from pycg3d.cg3d_point import CG3dPoint
from pycg3d.transform.cg3d_translate import CG3dXtranslateTF, CG3dYtranslateTF
p1 = CG3dPoint(0.0, 0.0, 0.0)
tf1 = CG3dXtranslateTF(1.0) # translate along X-axis by 1.0
p2 = p1.transform(tf1) # p2 == CG3dPoint(1.0, 0.0, 0.0)
tf2 = CG3dYtranslateTF(2.0) # translate along Y-axis by 1.0
p3 = p2.transform(tf2) # p3 == CG3dPoint(1.0, 2.0, 0.0)
p4 = p1.transform(tf1).transform(tf2) # chained transformations, p4 == CG3dPoint(1.0, 2.0, 0.0)
- Class CG3dTranslateTF : Translation alone any direction
- Class CG3dX(Y/Z)translateTF : Translation alone X/Y/Z-axis
Rotation
- Class CG3dRotateTF : Rotation about an arbitrary axis
- Class CG3dX(Y/Z)rotateTF : Rotation about X/Y/Z axis
Reflection
Mirror point(-1.0, 0.0, 0.0) to Y-Z Plane:
from pycg3d.cg3d_point import CG3dPoint
from pycg3d.cg3d_point import CG3dVector
from pycg3d.cg3d_plane import CG3dPlanePN
from pycg3d.transform.cg3d_reflect import CG3dPlaneMirrorTF
p1 = CG3dPoint(-1.0, 0.0, 0.0)
yz_plane = CG3dPlanePN(CG3dPoint(0.0, 0.0, 0.0), CG3dVector(1.0, 0.0, 0.0))
mirror = CG3dPlaneMirrorTF(yz_plane)
p2 = p1.transform(mirror) # p2 == CG3dPoint(1.0, 0.0, 0.0)
- Class CG3dPlaneMirrorTF: Reflection by mirroring to a Plane
Utility functions
Use utility functions:
from pycg3d import utils
from pycg3d.cg3d_point import CG3dPoint
utils.distance([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]) # 1.0
utils.distance(CG3dPoint(0.0, 0.0, 0.0), CG3dPoint(1.0, 0.0, 0.0)) # 1.0
distance(p1, p2):
dot_product(v1, v2):
- compute dot production of two vectors
- param v1: vector 1 (a list with 3 floats or CG3dVector)
- param v2: vector 2 (a list with 3 floats or CG3dVector)
- return: float
cross_product(v1, v2):
- compute cross production of two vectors
- param v1: vector 1 (a list with 3 floats or CG3dVector)
- param v2: vector 2 (a list with 3 floats or CG3dVector)
- return: CG3dVector
mirror_point_to_plane(point, plane):
Changelog
- 2017/2/16
- v0.0.1 released