Skip to content

Commit 2042d25

Browse files
chenkasirerchenkasirer
committed
standardized docstrings in compas_rhino
1 parent 7879313 commit 2042d25

File tree

5 files changed

+220
-90
lines changed

5 files changed

+220
-90
lines changed

‎src/compas_rhino/geometry/brep/brep.py‎

Lines changed: 118 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,31 @@
2020

2121

2222
class RhinoBrep(Brep):
23-
"""
24-
Rhino Brep backend class.
25-
Wraps around and allows serialization and de-serialization of a `Rhino.Geometry.Brep`
23+
"""Rhino Brep backend class.
24+
25+
Wraps around and allows serialization and de-serialization of a :class:`Rhino.Geometry.Brep`.
26+
27+
Attributes
28+
----------
29+
native_brep : :class:`Rhino.Geometry.Brep`
30+
The underlying Rhino Brep instance,
31+
vertices : list[:class:`~compas_rhino.geometry.RhinoBrepVertex`], read-only
32+
The list of vertices which comprise this Brep,
33+
points : list[:class:`~compas.geometry.Point`], read-only
34+
The list of vertex geometries as points in 3D space,
35+
edges : list[:class:`~compas_rhino.geometry.RhinoBrepEdge`], read-only
36+
The list of edges which comprise this brep,
37+
loops : list[:class:`~compas_rhino.geometry.RhinoBrepLoop`], read-only
38+
The list of loops which comprise this brep,
39+
faces : list[:class:`~compas_rhino.geometry.RhinoBrepFace`], read-only
40+
The list of faces which comprise this brep,
41+
frame : :class:`~compas.geometry.Frame`, read-only
42+
The brep's origin (Frame.worldXY()),
43+
area : float, read-only
44+
The calculated area of this brep.
45+
volume : float, read-only
46+
The calculated volume of this brep.
47+
2648
"""
2749

2850
# this makes de-serialization backend-agnostic.
@@ -40,20 +62,6 @@ def __init__(self, brep=None):
4062
super(RhinoBrep, self).__init__()
4163
self._brep = brep or Rhino.Geometry.Brep()
4264

43-
# ==============================================================================
44-
# Constructors
45-
# ==============================================================================
46-
47-
@classmethod
48-
def from_brep(cls, rhino_brep):
49-
brep = cls(rhino_brep)
50-
return brep
51-
52-
@classmethod
53-
def from_box(cls, box):
54-
rhino_box = box_to_rhino(box)
55-
return cls.from_brep(rhino_box.ToBrep())
56-
5765
# ==============================================================================
5866
# Data
5967
# ==============================================================================
@@ -67,15 +75,6 @@ def data(self):
6775

6876
@data.setter
6977
def data(self, data):
70-
"""
71-
Parameters
72-
----------
73-
data
74-
75-
Returns
76-
-------
77-
78-
"""
7978
faces = []
8079
for facedata in data["faces"]:
8180
face = RhinoBrepFace.from_data(facedata)
@@ -88,13 +87,6 @@ def data(self, data):
8887

8988
@property
9089
def native_brep(self):
91-
"""
92-
Returns the native representation of this Brep.
93-
94-
Returns
95-
-------
96-
:class: `Rhino.Geometry.Brep`
97-
"""
9890
return self._brep
9991

10092
@property
@@ -135,18 +127,101 @@ def volume(self):
135127
if self._brep:
136128
return self._brep.GetVolume()
137129

138-
def _create_native_brep(self, faces):
130+
# ==============================================================================
131+
# Constructors
132+
# ==============================================================================
133+
134+
@classmethod
135+
def from_brep(cls, rhino_brep):
136+
"""Constructs a RhinoBrep from an instance of a Rhino brep
137+
138+
Parameters
139+
----------
140+
rhino_brep : :class:`Rhino.Geometry.Brep`
141+
The instance of Rhino brep to wrap.
142+
143+
Returns
144+
-------
145+
:class:`compas_rhino.geometry.RhinoBrep`
146+
147+
"""
148+
brep = cls(rhino_brep)
149+
return brep
150+
151+
@classmethod
152+
def from_box(cls, box):
153+
"""Create a RhinoBrep from a box.
154+
155+
Parameters
156+
----------
157+
box : :class:`~compas.geometry.Box`
158+
The box geometry of the brep.
159+
160+
Returns
161+
-------
162+
:class:`~compas_rhino.geometry.RhinoBrep`
163+
164+
"""
165+
rhino_box = box_to_rhino(box)
166+
return cls.from_brep(rhino_box.ToBrep())
167+
168+
# ==============================================================================
169+
# Methods
170+
# ==============================================================================
171+
172+
def transform(self, matrix):
173+
"""Transform this Brep by given transformation matrix
174+
175+
Parameters
176+
----------
177+
matrix: :class:`~compas.geometry.Transformation`
178+
The transformation matrix by which to transform this Brep.
179+
180+
Returns
181+
-------
182+
None
183+
139184
"""
140-
Source: https://github.com/mcneel/rhino-developer-samples/blob/3179a8386a64602ee670cc832c77c561d1b0944b/rhinocommon/cs/SampleCsCommands/SampleCsTrimmedPlane.cs
141-
Things need to be defined in a valid brep:
142-
1- Vertices
143-
2- 3D Curves (geometry)
144-
3- Edges (topology - reference curve geometry)
145-
4- Surfaces (geometry)
146-
5- Faces (topology - reference surface geometry)
147-
6- Loops (2D parameter space of faces)
148-
4- Trims and 2D curves (2D parameter space of edges)
185+
self._brep.Transform(xform_to_rhino(matrix))
186+
187+
def trim(self, trimming_plane, tolerance=TOLERANCE):
188+
"""Trim this brep by the given trimming plane
189+
190+
Parameters
191+
----------
192+
trimming_plane : :class:`~compas.geometry.Frame` or :class:`~compas.geometry.Plane`
193+
The frame or plane to use when trimming.
194+
195+
tolerance : float
196+
The precision to use for the trimming operation.
197+
198+
Returns
199+
-------
200+
None
201+
149202
"""
203+
rhino_frame = frame_to_rhino(trimming_plane)
204+
rhino_frame.Flip()
205+
results = self._brep.Trim(rhino_frame, tolerance)
206+
if not results:
207+
raise BrepTrimmingError("Trim operation ended with no result")
208+
209+
self._brep = results[0]
210+
211+
# ==============================================================================
212+
# Other Methods
213+
# ==============================================================================
214+
215+
def _create_native_brep(self, faces):
216+
# Source: https://github.com/mcneel/rhino-developer-samples/blob/3179a8386a64602ee670cc832c77c561d1b0944b/rhinocommon/cs/SampleCsCommands/SampleCsTrimmedPlane.cs
217+
# Things need to be defined in a valid brep:
218+
# 1- Vertices
219+
# 2- 3D Curves (geometry)
220+
# 3- Edges (topology - reference curve geometry)
221+
# 4- Surfaces (geometry)
222+
# 5- Faces (topology - reference surface geometry)
223+
# 6- Loops (2D parameter space of faces)
224+
# 4- Trims and 2D curves (2D parameter space of edges)
150225
self._brep = Rhino.Geometry.Brep()
151226
for face in faces:
152227
rhino_face, rhino_surface = self._create_brep_face(face)
@@ -213,36 +288,3 @@ def _create_trim_curve(rhino_edge, rhino_surface):
213288
curve_2d = rhino_surface.Pullback(rhino_edge.EdgeCurve, TOLERANCE)
214289
curve_2d.Reverse()
215290
return curve_2d
216-
217-
# ==============================================================================
218-
# Methods
219-
# ==============================================================================
220-
221-
def transform(self, matrix):
222-
"""
223-
Transform this Brep by given transformation matrix
224-
Parameters
225-
----------
226-
matrix: :class:`~compas.geometry.Transformation`
227-
The transformation matrix by which to transform this Brep.
228-
"""
229-
self._brep.Transform(xform_to_rhino(matrix))
230-
231-
def trim(self, trimming_plane, tolerance=TOLERANCE):
232-
"""Trim this brep by the given trimming plane
233-
234-
Parameters
235-
----------
236-
trimming_plane
237-
:class:`~compas.geometry.Frame`
238-
239-
tolerance: the tolerance to use when trimming
240-
float
241-
"""
242-
rhino_frame = frame_to_rhino(trimming_plane)
243-
rhino_frame.Flip()
244-
results = self._brep.Trim(rhino_frame, tolerance)
245-
if not results:
246-
raise BrepTrimmingError("Trim operation ended with no result")
247-
248-
self._brep = results[0]

‎src/compas_rhino/geometry/brep/edge.py‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,24 @@
1212

1313

1414
class RhinoBrepEdge(BrepEdge):
15-
"""A wrapper for Rhino.Geometry.BrepEdge"""
15+
"""A wrapper for Rhino.Geometry.BrepEdge
16+
17+
Attributes
18+
----------
19+
curve : :class:`Rhino.Geometry.Curve3D`
20+
The underlying geometry of this edge.
21+
start_vertex : :class:`~compas_rhino.geometry.RhinoBrepVertex`
22+
The start vertex of this edge.
23+
end_vertex : :class:`~compas_rhino.geometry.RhinoBrepVertex`
24+
The end vertex of this edge.
25+
vertices : list[:class:`~compas_rhino.geometry.RhinoBrepVertex`]
26+
The list of vertices which comprise this edge (start and end)
27+
is_circle : bool, read-only
28+
True if the geometry of this edge is a circle, False otherwise.
29+
is_line : bool, read-only
30+
True if the geometry of this edge is a line, False otherwise.
31+
32+
"""
1633

1734
def __init__(self, rhino_edge=None):
1835
super(RhinoBrepEdge, self).__init__()
@@ -29,6 +46,10 @@ def _set_edge(self, native_edge):
2946
self._start_vertex = RhinoBrepVertex(self._edge.StartVertex)
3047
self._end_vertex = RhinoBrepVertex(self._edge.EndVertex)
3148

49+
# ==============================================================================
50+
# Data
51+
# ==============================================================================
52+
3253
@property
3354
def data(self):
3455
if self.is_line:
@@ -56,6 +77,10 @@ def data(self, value):
5677
self._start_vertex._point = Point.from_data(value["points"][0])
5778
self._end_vertex._point = Point.from_data(value["points"][1])
5879

80+
# ==============================================================================
81+
# Properties
82+
# ==============================================================================
83+
5984
@property
6085
def curve(self):
6186
return self._curve

‎src/compas_rhino/geometry/brep/face.py‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,24 @@
55

66

77
class RhinoBrepFace(BrepFace):
8-
"""A wrapper for Rhino.Geometry.BrepFace"""
8+
"""A wrapper for Rhino.Geometry.BrepFace
9+
10+
Attributes
11+
----------
12+
native_surface : :class:`Rhino.Geometry.Surface`
13+
The rhino native underlying geometry of this face.
14+
loops : list[:class:`compas_rhino.geometry.RhinoBrepLoop`]
15+
The list of loops which comprise this face.
16+
surface : :class:`compas_rhino.geometry.RhinoNurbsSurface`
17+
The compas_rhino wrapper of the underlying geometry of this face.
18+
boundary : :class:`compas_rhino.geometry.RhinoBrepLoop`
19+
The loop which defines the outer boundary of this face.
20+
holes : list[:class:`compas_rhino.geometry.RhinoBrepLoop`]
21+
The list of loops which comprise the holes of this brep, if any.
22+
is_plane : float, read-only
23+
True if the geometry of this face is a plane, False otherwise.
24+
25+
"""
926

1027
TOLERANCE = 1e-6
1128

@@ -22,6 +39,10 @@ def _set_face(self, native_face):
2239
self._loops = [RhinoBrepLoop(loop) for loop in self._face.Loops]
2340
self._surface = RhinoNurbsSurface.from_rhino(self._face.ToNurbsSurface()) # surface in Rhino will always be NURBS
2441

42+
# ==============================================================================
43+
# Data
44+
# ==============================================================================
45+
2546
@property
2647
def data(self):
2748
boundary = self._loops[0].data
@@ -36,6 +57,10 @@ def data(self, value):
3657
# TODO: should we check surface type here? should we support surfaces other than NURBS?
3758
self._surface = RhinoNurbsSurface.from_data(value["surface"])
3859

60+
# ==============================================================================
61+
# Properties
62+
# ==============================================================================
63+
3964
@property
4065
def native_surface(self):
4166
if self._surface:

‎src/compas_rhino/geometry/brep/loop.py‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,18 @@
66

77

88
class LoopType(object):
9+
"""Represents the type of a brep loop.
10+
11+
Attributes
12+
----------
13+
UNKNOWN
14+
OUTER
15+
INNTER
16+
SLIT
17+
CURVE_ON_SURFACE
18+
POINT_ON_SURFACE
19+
20+
"""
921
UNKNOWN = 0
1022
OUTER = 1
1123
INNTER = 2
@@ -15,7 +27,20 @@ class LoopType(object):
1527

1628

1729
class RhinoBrepLoop(BrepLoop):
18-
"""A wrapper for Rhino.Geometry.BrepLoop"""
30+
"""A wrapper for Rhino.Geometry.BrepLoop
31+
32+
Attributes
33+
----------
34+
edges : list[:class:`~compas_rhino.geometry.RhinoBrepLoop`]
35+
The list of edges which comprise this loop.
36+
loop_type : :class:`~compas_rhino.geometry.brep.loop.LoopType`
37+
The type of this loop.
38+
is_outer : bool, read-only
39+
True if this loop is an outer boundary, False otherwise.
40+
is_inner : bool, read-only
41+
True if this loop is an inner hole, False otherwise.
42+
43+
"""
1944

2045
def __init__(self, rhino_loop=None):
2146
super(RhinoBrepLoop, self).__init__()
@@ -30,6 +55,10 @@ def _set_loop(self, native_loop):
3055
self._type = int(self._loop.LoopType)
3156
self._edges = [RhinoBrepEdge(t.Edge) for t in self._loop.Trims]
3257

58+
# ==============================================================================
59+
# Data
60+
# ==============================================================================
61+
3362
@property
3463
def data(self):
3564
return [e.data for e in self._edges]
@@ -38,6 +67,10 @@ def data(self):
3867
def data(self, value):
3968
self._edges = [RhinoBrepEdge.from_data(e_data) for e_data in value]
4069

70+
# ==============================================================================
71+
# Properties
72+
# ==============================================================================
73+
4174
@property
4275
def edges(self):
4376
return self._edges

0 commit comments

Comments
 (0)