Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docstrings #177

Merged
merged 2 commits into from
Jun 2, 2023
Merged

Add docstrings #177

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
697f3a8
Add docstrings
martinRenou Jun 2, 2023
30dfe28
Update jupytercad/notebook/cad_document.py
martinRenou Jun 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 122 additions & 4 deletions jupytercad/notebook/cad_document.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,13 @@


class CadDocument(Widget):
"""
Create a new CadDocument object.

:param path: the path to the file that you would like to open. If not provided, a new empty document will be created.
"""
def __init__(self, path: Optional[str] = None):
comm_data = CadDocument.path_to_comm(path)
comm_data = CadDocument._path_to_comm(path)

super().__init__(name="@jupytercad:widget", open_comm=True, comm_data=comm_data)

Expand All @@ -43,12 +48,15 @@ def __init__(self, path: Optional[str] = None):

@property
def objects(self) -> List[str]:
"""
Get the list of objects that the document contains as a list of strings.
"""
if self._objects_array:
return [x["name"] for x in self._objects_array]
return []

@classmethod
def path_to_comm(cls, filePath: Optional[str]) -> Dict:
def _path_to_comm(cls, filePath: Optional[str]) -> Dict:
path = None
format = None
contentType = None
Expand Down Expand Up @@ -110,6 +118,16 @@ def add_occ_shape(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Add an Open Cascade TopoDS shape to the document. You need pythonocc-core installed in order to use this method.

:param shape: The Open Cascade shape to add.
:param name: The name that will be used for the object in the document.
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
try:
from OCC.Core.BRepTools import breptools_Write
except ImportError:
Expand Down Expand Up @@ -148,6 +166,18 @@ def add_box(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Add a box to the document.

:param name: The name that will be used for the object in the document.
:param length: The length of the box.
:param width: The width of the box.
:param height: The height of the box.
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
data = {
"shape": Parts.Part__Box.value,
"name": name if name else self._new_name("Box"),
Expand Down Expand Up @@ -175,6 +205,19 @@ def add_cone(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Add a cone to the document.

:param name: The name that will be used for the object in the document.
:param radius1: The bottom radius of the cone.
:param radius2: The top radius of the cone.
:param height: The height of the cone.
:param angle: The revolution angle of the cone (0: no cone, 180: half cone, 360: full cone).
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
data = {
"shape": Parts.Part__Cone.value,
"name": name if name else self._new_name("Cone"),
Expand Down Expand Up @@ -202,6 +245,18 @@ def add_cylinder(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Add a cylinder to the document.

:param name: The name that will be used for the object in the document.
:param radius: The radius of the cylinder.
:param height: The height of the cylinder.
:param angle: The revolution angle of the cylinder (0: no cylinder, 180: half cylinder, 360: full cylinder).
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
data = {
"shape": Parts.Part__Cylinder.value,
"name": name if name else self._new_name("Cylinder"),
Expand Down Expand Up @@ -229,6 +284,19 @@ def add_sphere(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Add a sphere to the document.

:param name: The name that will be used for the object in the document.
:param radius: The radius of the sphere.
:param angle1: The revolution angle of the sphere on the X axis (0: no sphere, 180: half sphere, 360: full sphere).
:param angle2: The revolution angle of the sphere on the Y axis (0: no sphere, 180: half sphere, 360: full sphere).
:param angle3: The revolution angle of the sphere on the Z axis (0: no sphere, 180: half sphere, 360: full sphere).
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
data = {
"shape": Parts.Part__Sphere.value,
"name": name if name else self._new_name("Sphere"),
Expand Down Expand Up @@ -258,6 +326,20 @@ def add_torus(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Add a torus to the document.

:param name: The name that will be used for the object in the document.
:param radius1: The outer radius of the torus.
:param radius2: The inner radius of the torus.
:param angle1: The revolution angle of the torus on the X axis (0: no torus, 180: half torus, 360: full torus).
:param angle2: The revolution angle of the torus on the Y axis (0: no torus, 180: half torus, 360: full torus).
:param angle3: The revolution angle of the torus on the Z axis (0: no torus, 180: half torus, 360: full torus).
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
data = {
"shape": Parts.Part__Torus.value,
"name": name if name else self._new_name("Torus"),
Expand Down Expand Up @@ -286,6 +368,18 @@ def cut(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Apply a cut boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.

:param name: The name that will be used for the object in the document.
:param base: The base object that will be used for the cut. Can be the name of the object or its index in the objects list.
:param tool: The tool object that will be used for the cut. Can be the name of the object or its index in the objects list.
:param refine: Whether or not to refine the mesh during the cut computation.
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
base, tool = self._get_boolean_operands(base, tool)

data = {
Expand All @@ -312,11 +406,23 @@ def fuse(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Apply a union boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.

:param name: The name that will be used for the object in the document.
:param shape1: The first object used for the union. Can be the name of the object or its index in the objects list.
:param shape2: The first object used for the union. Can be the name of the object or its index in the objects list.
:param refine: Whether or not to refine the mesh during the union computation.
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
shape1, shape2 = self._get_boolean_operands(shape1, shape2)

data = {
"shape": Parts.Part__MultiFuse.value,
"name": name if name else self._new_name("Cut"),
"name": name if name else self._new_name("Fuse"),
"parameters": {
"Shapes": [shape1, shape2],
"Refine": refine,
Expand All @@ -337,11 +443,23 @@ def intersect(
rotation_axis: List[float] = [0, 0, 1],
rotation_angle: float = 0,
) -> CadDocument:
"""
Apply a intersection boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.

:param name: The name that will be used for the object in the document.
:param shape1: The first object used for the intersection. Can be the name of the object or its index in the objects list.
:param shape2: The first object used for the intersection. Can be the name of the object or its index in the objects list.
:param refine: Whether or not to refine the mesh during the intersection computation.
:param position: The shape 3D position.
:param rotation_axis: The 3D axis used for the rotation.
:param rotation_angle: The shape rotation angle, in degrees.
:return: The document itself.
"""
shape1, shape2 = self._get_boolean_operands(shape1, shape2)

data = {
"shape": Parts.Part__MultiCommon.value,
"name": name if name else self._new_name("Cut"),
"name": name if name else self._new_name("Intersection"),
"parameters": {
"Shapes": [shape1, shape2],
"Refine": refine,
Expand Down