== console ==
[blender-staging.git] / doc / python_api / epy / Geometry.py
1 # Blender.Geometry module and its subtypes
2
3 """
4 The Blender.Geometry submodule.
5
6 Geometry
7 ========
8 (when accessing it from the Game Engine use Geometry instead of Blender.Geometry)
9
10 This new module provides access to a geometry function.
11 """
12
13 def Intersect(vec1, vec2, vec3, ray, orig, clip=1):
14   """
15   Return the intersection between a ray and a triangle, if possible, return None otherwise.
16   @type vec1: Vector object.
17   @param vec1: A 3d vector, one corner of the triangle.
18   @type vec2: Vector object.
19   @param vec2: A 3d vector, one corner of the triangle.
20   @type vec3: Vector object.
21   @param vec3: A 3d vector, one corner of the triangle.
22   @type ray: Vector object.
23   @param ray: A 3d vector, the orientation of the ray. the length of the ray is not used, only the direction.
24   @type orig: Vector object.
25   @param orig: A 3d vector, the origin of the ray.
26   @type clip: integer
27   @param clip: if 0, don't restrict the intersection to the area of the triangle, use the infinite plane defined by the triangle.
28   @rtype: Vector object
29   @return: The intersection between a ray and a triangle, if possible, None otherwise.
30   """
31
32 def TriangleArea(vec1, vec2, vec3):
33   """
34   Return the area size of the 2D or 3D triangle defined.
35   @type vec1: Vector object.
36   @param vec1: A 2d or 3d vector, one corner of the triangle.
37   @type vec2: Vector object.
38   @param vec2: A 2d or 3d vector, one corner of the triangle.
39   @type vec3: Vector object.
40   @param vec3: A 2d or 3d vector, one corner of the triangle.
41   @rtype: float
42   @return: The area size of the 2D or 3D triangle defined.
43   """
44
45 def TriangleNormal(vec1, vec2, vec3):
46   """
47   Return the normal of the 3D triangle defined.
48   @type vec1: Vector object.
49   @param vec1: A 3d vector, one corner of the triangle.
50   @type vec2: Vector object.
51   @param vec2: A 3d vector, one corner of the triangle.
52   @type vec3: Vector object.
53   @param vec3: A 3d vector, one corner of the triangle.
54   @rtype: float
55   @return: The normal of the 3D triangle defined.
56   """
57
58 def QuadNormal(vec1, vec2, vec3, vec4):
59   """
60   Return the normal of the 3D quad defined.
61   @type vec1: Vector object.
62   @param vec1: A 3d vector, the first vertex of the quad.
63   @type vec2: Vector object.
64   @param vec2: A 3d vector, the second vertex of the quad.
65   @type vec3: Vector object.
66   @param vec3: A 3d vector, the third vertex of the quad.
67   @type vec4: Vector object.
68   @param vec4: A 3d vector, the fourth vertex of the quad.
69   @rtype: float
70   @return: The normal of the 3D quad defined.
71   """
72
73 def LineIntersect(vec1, vec2, vec3, vec4):
74   """
75   Return a tuple with the points on each line respectively closest to the other
76   (when both lines intersect, both vector hold the same value).
77   The lines are evaluated as infinite lines in space, the values returned may not be between the 2 points given for each line.
78   @type vec1: Vector object.
79   @param vec1: A 3d vector, one point on the first line.
80   @type vec2: Vector object.
81   @param vec2: A 3d vector, another point on the first line.
82   @type vec3: Vector object.
83   @param vec3: A 3d vector, one point on the second line.
84   @type vec4: Vector object.
85   @param vec4: A 3d vector, another point on the second line.
86   @rtype: (Vector object, Vector object)
87   @return: A tuple with the points on each line respectively closest to the other.
88   """
89
90 def PolyFill(polylines):
91         """
92         Takes a list of polylines and calculates triangles that would fill in the polylines.
93         Multiple lines can be used to make holes inside a polyline, or fill in 2 separate lines at once.
94         @type polylines: List of lists containing vectors, each representing a closed polyline.
95         @rtype: list
96         @return: a list if tuples each a tuple of 3 ints representing a triangle indexing the points given.
97         @note: 2D Vectors will have an assumed Z axis of zero, 4D Vectors W axis is ignored.
98         @note: The order of points in a polyline effect the direction returned triangles face, reverse the order of a polyline to flip the normal of returned faces.
99
100         I{B{Example:}}
101
102         The example below creates 2 polylines and fills them in with faces, then makes a mesh in the current scene::
103                 import Blender
104                 Vector= Blender.mathutils.Vector
105
106                 # Outline of 5 points
107                 polyline1= [Vector(-2.0, 1.0, 1.0), Vector(-1.0, 2.0, 1.0), Vector(1.0, 2.0, 1.0), Vector(1.0, -1.0, 1.0), Vector(-1.0, -1.0, 1.0)]
108                 polyline2= [Vector(-1, 1, 1.0), Vector(0, 1, 1.0), Vector(0, 0, 1.0), Vector(-1.0, 0.0, 1.0)]
109                 fill= Blender.Geometry.PolyFill([polyline1, polyline2])
110
111                 # Make a new mesh and add the truangles into it
112                 me= Blender.Mesh.New()
113                 me.verts.extend(polyline1)
114                 me.verts.extend(polyline2)
115                 me.faces.extend(fill) # Add the faces, they reference the verts in polyline 1 and 2
116
117                 scn = Blender.Scene.GetCurrent()
118                 ob = scn.objects.new(me)
119                 Blender.Redraw()
120         """
121
122 def LineIntersect2D(vec1, vec2, vec3, vec4):
123         """
124         Takes 2 lines vec1, vec2 for the 2 points of the first line and vec2, vec3 for the 2 points of the second line.
125         @rtype: Vector
126         @return: a 2D Vector for the intersection or None where there is no intersection.
127         """
128
129 def ClosestPointOnLine(pt, vec1, vec2):
130         """
131         Takes 2 lines vec1, vec2 for the 2 points of the first line and vec2, vec3 for the 2 points of the second line.
132         @rtype: tuple
133         @return: a tuple containing a vector and a float, the vector is the closest point on the line, the float is the position on the line, between 0 and 1 the point is on the line.
134         """
135
136 def PointInTriangle2D(pt, tri_pt1, tri_pt2, tri_pt3):
137         """
138         Takes 4 vectors (one for the test point and 3 for the triangle)
139         This is a 2d function so only X and Y are used, Z and W will be ignored.
140         @rtype: int
141         @return: 1 for a clockwise intersection, -1 for counter clockwise intersection, 0 when there is no intersection.
142         """
143
144 def PointInQuad2D(pt, quad_pt1, quad_pt2, quad_pt3):
145         """
146         Takes 5 vectors (one for the test point and 5 for the quad)
147         This is a 2d function so only X and Y are used, Z and W will be ignored.
148         @rtype: int
149         @return: 1 for a clockwise intersection, -1 for counter clockwise intersection, 0 when there is no intersection.
150         """
151
152 def BoxPack2D(boxlist):
153         """
154         Takes a list of 2D boxes and packs them into a square.
155         Each box in boxlist must be a list of at least 4 items - [x,y,w,h], after running this script,
156         the X and Y values in each box will be moved to packed, non overlapping locations.
157         
158         Example::
159
160                 # Make 500 random boxes, pack them and make a mesh from it
161                 from Blender import Geometry, Scene, Mesh
162                 import random
163                 boxes = []
164                 for i in xrange(500):
165                         boxes.append( [0,0, random.random()+0.1, random.random()+0.1] )
166                 boxsize = Geometry.BoxPack2D(boxes)
167                 print 'BoxSize', boxsize
168                 me = Mesh.New()
169                 for x in boxes:
170                         me.verts.extend([(x[0],x[1], 0), (x[0],x[1]+x[3], 0), (x[0]+x[2],x[1]+x[3], 0), (x[0]+x[2],x[1], 0) ])
171                         v1= me.verts[-1]
172                         v2= me.verts[-2]
173                         v3= me.verts[-3]
174                         v4= me.verts[-4]
175                         me.faces.extend([(v1,v2,v3,v4)])
176                 scn = Scene.GetCurrent()
177                 scn.objects.new(me)
178         
179         @note: Each boxlist item can be longer then 4, the extra items are ignored and stay untouched.
180         @rtype: tuple
181         @return: a tuple pair - (width, height) of all the packed boxes.
182         """
183 def BezierInterp(vec_knot_1, vec_handle_1, vec_handle_2, vec_knot_2, resolution):
184         """
185         Takes 4 vectors representing a bezier curve and returns a list of vector points.
186         @note: any vector size is supported, the largest dimension from the input will be used for all returned vectors/
187         @rtype: list
188         @return: a list of vectors the size of resolution including the start and end points (vec_knot_1 and vec_knot_2)
189         """