From c5cd69569ea62a477cf8e49271b63e2f7d39110d Mon Sep 17 00:00:00 2001 From: Dogukan Karatas Date: Wed, 5 Mar 2025 12:50:44 +0100 Subject: [PATCH] docs poc --- .../api/client.md | 0 .../objects/Data_Objects/DataObject.md | 1 + .../objects/Data_Objects/QgisObject.md | 1 + .../objects/Interfaces/IBlenderObject.md | 1 + .../objects/Interfaces/ICurve.md | 1 + .../objects/Interfaces/IDataObject.md | 1 + .../objects/Interfaces/IDisplayValue.md | 1 + .../objects/Interfaces/IGisObject.md | 1 + .../objects/Interfaces/IHasArea.md | 1 + .../objects/Interfaces/IHasUnits.md | 1 + .../objects/Interfaces/IHasVolume.md | 1 + .../objects/Interfaces/IProperties.md | 1 + .../objects/Other/RenderMaterial.md | 1 + .../objects/Primitve/Interval.md | 1 + .../objects/Proxies/ColorProxy.md | 1 + .../objects/Proxies/GroupProxy.md | 1 + .../Proxies/InstanceDefinitionProxy.md | 1 + .../objects/Proxies/InstanceProxy.md | 1 + .../objects/Proxies/RenderMaterialProxy.md | 1 + .../objects/base.md | 0 .../objects/geometry/Arc.md} | 0 .../Specklepy_SDK/objects/geometry/Box.md | 1 + .../Specklepy_SDK/objects/geometry/Circle.md | 1 + .../objects/geometry/ControlPoint.md | 1 + .../Specklepy_SDK/objects/geometry/Ellipse.md | 1 + .../Specklepy_SDK/objects/geometry/Line.md | 1 + .../Specklepy_SDK/objects/geometry/Mesh.md | 1 + .../Specklepy_SDK/objects/geometry/Plane.md | 1 + .../Specklepy_SDK/objects/geometry/Point.md | 1 + .../objects/geometry/Point_Cloud.md | 1 + .../objects/geometry/Polycurve.md | 1 + .../objects/geometry/Polyline.md | 1 + .../Specklepy_SDK/objects/geometry/Spiral.md | 1 + .../Specklepy_SDK/objects/geometry/Surface.md | 1 + .../Specklepy_SDK/objects/geometry/Vector.md | 1 + src/docs/assets/speckle_logo.png | Bin 0 -> 386 bytes src/docs/index.md | 36 ++++++++----- src/mkdocs.yml | 48 +++++++++++++++--- src/specklepy/objects/base.py | 24 +++++++++ src/specklepy/objects/data_objects.py | 4 ++ src/specklepy/objects/geometry/arc.py | 41 ++++++++++++--- src/specklepy/objects/geometry/box.py | 34 ++++++++++++- 42 files changed, 193 insertions(+), 26 deletions(-) rename src/docs/{specklepy => Specklepy_SDK}/api/client.md (100%) create mode 100644 src/docs/Specklepy_SDK/objects/Data_Objects/DataObject.md create mode 100644 src/docs/Specklepy_SDK/objects/Data_Objects/QgisObject.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IBlenderObject.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/ICurve.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IDataObject.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IDisplayValue.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IGisObject.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IHasArea.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IHasUnits.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IHasVolume.md create mode 100644 src/docs/Specklepy_SDK/objects/Interfaces/IProperties.md create mode 100644 src/docs/Specklepy_SDK/objects/Other/RenderMaterial.md create mode 100644 src/docs/Specklepy_SDK/objects/Primitve/Interval.md create mode 100644 src/docs/Specklepy_SDK/objects/Proxies/ColorProxy.md create mode 100644 src/docs/Specklepy_SDK/objects/Proxies/GroupProxy.md create mode 100644 src/docs/Specklepy_SDK/objects/Proxies/InstanceDefinitionProxy.md create mode 100644 src/docs/Specklepy_SDK/objects/Proxies/InstanceProxy.md create mode 100644 src/docs/Specklepy_SDK/objects/Proxies/RenderMaterialProxy.md rename src/docs/{specklepy => Specklepy_SDK}/objects/base.md (100%) rename src/docs/{specklepy/objects/geometry/arc.md => Specklepy_SDK/objects/geometry/Arc.md} (100%) create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Box.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Circle.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/ControlPoint.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Ellipse.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Line.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Mesh.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Plane.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Point.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Point_Cloud.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Polycurve.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Polyline.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Spiral.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Surface.md create mode 100644 src/docs/Specklepy_SDK/objects/geometry/Vector.md create mode 100644 src/docs/assets/speckle_logo.png diff --git a/src/docs/specklepy/api/client.md b/src/docs/Specklepy_SDK/api/client.md similarity index 100% rename from src/docs/specklepy/api/client.md rename to src/docs/Specklepy_SDK/api/client.md diff --git a/src/docs/Specklepy_SDK/objects/Data_Objects/DataObject.md b/src/docs/Specklepy_SDK/objects/Data_Objects/DataObject.md new file mode 100644 index 0000000..960c79b --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Data_Objects/DataObject.md @@ -0,0 +1 @@ +::: specklepy.objects.data_objects.DataObject diff --git a/src/docs/Specklepy_SDK/objects/Data_Objects/QgisObject.md b/src/docs/Specklepy_SDK/objects/Data_Objects/QgisObject.md new file mode 100644 index 0000000..3b98ec2 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Data_Objects/QgisObject.md @@ -0,0 +1 @@ +::: specklepy.objects.data_objects.QgisObject diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IBlenderObject.md b/src/docs/Specklepy_SDK/objects/Interfaces/IBlenderObject.md new file mode 100644 index 0000000..c9dc248 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IBlenderObject.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IBlenderObject diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/ICurve.md b/src/docs/Specklepy_SDK/objects/Interfaces/ICurve.md new file mode 100644 index 0000000..bee7d7d --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/ICurve.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.ICurve diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IDataObject.md b/src/docs/Specklepy_SDK/objects/Interfaces/IDataObject.md new file mode 100644 index 0000000..8109184 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IDataObject.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IDataObject diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IDisplayValue.md b/src/docs/Specklepy_SDK/objects/Interfaces/IDisplayValue.md new file mode 100644 index 0000000..7a9214f --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IDisplayValue.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IDisplayValue diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IGisObject.md b/src/docs/Specklepy_SDK/objects/Interfaces/IGisObject.md new file mode 100644 index 0000000..c9dc248 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IGisObject.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IBlenderObject diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IHasArea.md b/src/docs/Specklepy_SDK/objects/Interfaces/IHasArea.md new file mode 100644 index 0000000..3cd605b --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IHasArea.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IHasArea diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IHasUnits.md b/src/docs/Specklepy_SDK/objects/Interfaces/IHasUnits.md new file mode 100644 index 0000000..aad9401 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IHasUnits.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IHasUnits diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IHasVolume.md b/src/docs/Specklepy_SDK/objects/Interfaces/IHasVolume.md new file mode 100644 index 0000000..1854a5e --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IHasVolume.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IHasVolume diff --git a/src/docs/Specklepy_SDK/objects/Interfaces/IProperties.md b/src/docs/Specklepy_SDK/objects/Interfaces/IProperties.md new file mode 100644 index 0000000..72ad275 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Interfaces/IProperties.md @@ -0,0 +1 @@ +::: specklepy.objects.interfaces.IProperties diff --git a/src/docs/Specklepy_SDK/objects/Other/RenderMaterial.md b/src/docs/Specklepy_SDK/objects/Other/RenderMaterial.md new file mode 100644 index 0000000..196d188 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Other/RenderMaterial.md @@ -0,0 +1 @@ +::: specklepy.objects.other.RenderMaterial diff --git a/src/docs/Specklepy_SDK/objects/Primitve/Interval.md b/src/docs/Specklepy_SDK/objects/Primitve/Interval.md new file mode 100644 index 0000000..b00acf7 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Primitve/Interval.md @@ -0,0 +1 @@ +::: specklepy.objects.primitive.Interval diff --git a/src/docs/Specklepy_SDK/objects/Proxies/ColorProxy.md b/src/docs/Specklepy_SDK/objects/Proxies/ColorProxy.md new file mode 100644 index 0000000..d1c058f --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Proxies/ColorProxy.md @@ -0,0 +1 @@ +::: specklepy.objects.proxies.ColorProxy diff --git a/src/docs/Specklepy_SDK/objects/Proxies/GroupProxy.md b/src/docs/Specklepy_SDK/objects/Proxies/GroupProxy.md new file mode 100644 index 0000000..9fa9b0b --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Proxies/GroupProxy.md @@ -0,0 +1 @@ +::: specklepy.objects.proxies.GroupProxy diff --git a/src/docs/Specklepy_SDK/objects/Proxies/InstanceDefinitionProxy.md b/src/docs/Specklepy_SDK/objects/Proxies/InstanceDefinitionProxy.md new file mode 100644 index 0000000..6d976aa --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Proxies/InstanceDefinitionProxy.md @@ -0,0 +1 @@ +::: specklepy.objects.proxies.InstanceDefinitionProxy diff --git a/src/docs/Specklepy_SDK/objects/Proxies/InstanceProxy.md b/src/docs/Specklepy_SDK/objects/Proxies/InstanceProxy.md new file mode 100644 index 0000000..11ea69c --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Proxies/InstanceProxy.md @@ -0,0 +1 @@ +::: specklepy.objects.proxies.InstanceProxy diff --git a/src/docs/Specklepy_SDK/objects/Proxies/RenderMaterialProxy.md b/src/docs/Specklepy_SDK/objects/Proxies/RenderMaterialProxy.md new file mode 100644 index 0000000..7762bbb --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/Proxies/RenderMaterialProxy.md @@ -0,0 +1 @@ +::: specklepy.objects.proxies.RenderMaterialProxy diff --git a/src/docs/specklepy/objects/base.md b/src/docs/Specklepy_SDK/objects/base.md similarity index 100% rename from src/docs/specklepy/objects/base.md rename to src/docs/Specklepy_SDK/objects/base.md diff --git a/src/docs/specklepy/objects/geometry/arc.md b/src/docs/Specklepy_SDK/objects/geometry/Arc.md similarity index 100% rename from src/docs/specklepy/objects/geometry/arc.md rename to src/docs/Specklepy_SDK/objects/geometry/Arc.md diff --git a/src/docs/Specklepy_SDK/objects/geometry/Box.md b/src/docs/Specklepy_SDK/objects/geometry/Box.md new file mode 100644 index 0000000..8d09031 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Box.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.box.Box diff --git a/src/docs/Specklepy_SDK/objects/geometry/Circle.md b/src/docs/Specklepy_SDK/objects/geometry/Circle.md new file mode 100644 index 0000000..404850c --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Circle.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.circle.Circle diff --git a/src/docs/Specklepy_SDK/objects/geometry/ControlPoint.md b/src/docs/Specklepy_SDK/objects/geometry/ControlPoint.md new file mode 100644 index 0000000..6ee504b --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/ControlPoint.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.control_point.ControlPoint diff --git a/src/docs/Specklepy_SDK/objects/geometry/Ellipse.md b/src/docs/Specklepy_SDK/objects/geometry/Ellipse.md new file mode 100644 index 0000000..69842b3 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Ellipse.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.ellipse.Ellipse diff --git a/src/docs/Specklepy_SDK/objects/geometry/Line.md b/src/docs/Specklepy_SDK/objects/geometry/Line.md new file mode 100644 index 0000000..f9d6ad0 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Line.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.line.Line diff --git a/src/docs/Specklepy_SDK/objects/geometry/Mesh.md b/src/docs/Specklepy_SDK/objects/geometry/Mesh.md new file mode 100644 index 0000000..41a5cdb --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Mesh.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.mesh.Mesh diff --git a/src/docs/Specklepy_SDK/objects/geometry/Plane.md b/src/docs/Specklepy_SDK/objects/geometry/Plane.md new file mode 100644 index 0000000..e45189b --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Plane.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.plane.Plane diff --git a/src/docs/Specklepy_SDK/objects/geometry/Point.md b/src/docs/Specklepy_SDK/objects/geometry/Point.md new file mode 100644 index 0000000..29b16a7 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Point.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.point.Point diff --git a/src/docs/Specklepy_SDK/objects/geometry/Point_Cloud.md b/src/docs/Specklepy_SDK/objects/geometry/Point_Cloud.md new file mode 100644 index 0000000..65bceed --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Point_Cloud.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.point_cloud.PointCloud diff --git a/src/docs/Specklepy_SDK/objects/geometry/Polycurve.md b/src/docs/Specklepy_SDK/objects/geometry/Polycurve.md new file mode 100644 index 0000000..1d6b8f6 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Polycurve.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.polycurve.Polycurve diff --git a/src/docs/Specklepy_SDK/objects/geometry/Polyline.md b/src/docs/Specklepy_SDK/objects/geometry/Polyline.md new file mode 100644 index 0000000..80965b6 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Polyline.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.polyline.Polyline diff --git a/src/docs/Specklepy_SDK/objects/geometry/Spiral.md b/src/docs/Specklepy_SDK/objects/geometry/Spiral.md new file mode 100644 index 0000000..683cbff --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Spiral.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.spiral.Spiral diff --git a/src/docs/Specklepy_SDK/objects/geometry/Surface.md b/src/docs/Specklepy_SDK/objects/geometry/Surface.md new file mode 100644 index 0000000..0fc6725 --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Surface.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.surface.Surface diff --git a/src/docs/Specklepy_SDK/objects/geometry/Vector.md b/src/docs/Specklepy_SDK/objects/geometry/Vector.md new file mode 100644 index 0000000..633f5ab --- /dev/null +++ b/src/docs/Specklepy_SDK/objects/geometry/Vector.md @@ -0,0 +1 @@ +::: specklepy.objects.geometry.vector.Vector diff --git a/src/docs/assets/speckle_logo.png b/src/docs/assets/speckle_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..c4e2b6d1b479060ed04b0a9aa1f95d8a1625d224 GIT binary patch literal 386 zcmeAS@N?(olHy`uVBq!ia0vp^5+KaM1|%Pp+x`GjoCO|{#S9GG!XV7ZFl!D-1!HlL zyA#8@b22Z19F}xPUq=Rpjs4tz5?O(A;+`&!Ar*{or|$JTY#`El-Zb#1puIRJo0&Zm zvoQCoW2cTqsJY28$}P+fa5Fn{tSw?jC5v(6k%qw4OYA-GytY_-%T`wFr$=Y)o8rGG zGy%~m!=N_&#O0GI_x?28sO^e#qCx_h~SX_YUfEDwVW6fJEnngVy zzC6;fVy_U#!}-si{fgc`>Fje`I~&pOPp8Wys3t7kK5N&3Q}@GyS6z=e;UUjo$9=8r d\AppData\Roaming\Speckle` +- Linux: `$XDG_DATA_HOME` or by default `~/.local/share/Speckle` +- Mac: `~/.config/Speckle` diff --git a/src/mkdocs.yml b/src/mkdocs.yml index 72e3702..b978c67 100644 --- a/src/mkdocs.yml +++ b/src/mkdocs.yml @@ -1,6 +1,39 @@ -site_name: SpecklePy API Docs +site_name: Specklepy Docs theme: name: material + favicon: assets/speckle_logo.png + logo: assets/speckle_logo.png + features: + - navigation.tabs + palette: + # Palette toggle for light mode + - scheme: default + primary: white + toggle: + icon: material/weather-night + name: Switch to dark mode + + # Palette toggle for dark mode + - scheme: slate + primary: black + logo: assets/logo_white.png + toggle: + icon: material/weather-sunny + name: Switch to light mode + + + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + +extra_css: +- css/mkdocstrings.css plugins: - search @@ -9,6 +42,7 @@ plugins: python: paths: [.] options: + parameter_headings: false members_order: source separate_signature: true filters: ["!^_"] #Ignore _ prefixed properties @@ -18,11 +52,13 @@ plugins: show_signature_annotations: true signature_crossrefs: true show_if_no_docstring: true + show_labels: true + show_source: true + show_symbol_type_heading: true + show_symbol_type_toc: true + show_bases: false + heading_level: 3 + inventories: - url: https://docs.python.org/3/objects.inv domains: [py, std] - # selection: - # docstring_style: google # Ensures Google-style docstrings are parsed correctly - rendering: - show_root_heading: true - show_source: true diff --git a/src/specklepy/objects/base.py b/src/specklepy/objects/base.py index 3f49357..08329bf 100644 --- a/src/specklepy/objects/base.py +++ b/src/specklepy/objects/base.py @@ -323,6 +323,30 @@ def _validate_type(t: Optional[type], value: Any) -> Tuple[bool, Any]: @dataclass(kw_only=True) class Base(_RegisteringBase, speckle_type="Base"): + """Base class for all Speckle objects. + + The base object class is the foundation of all data being + transferred with Speckle. Any custom data structure that you want to transfer via + Speckle should inherit from it. + + Objects in Speckle are immutable for storage purposes. When any property changes, + the object gets a new identity (hash). This hash is stored in the `id` property + after serialization. + + Attributes: + id: Unique identifier (hash) for the object. This is typically + set automatically during serialization and depends on the object's properties. + applicationId: Optional identifier for the application that created + this object, can store the host application's native object ID. + + ```py title="Example" + from specklepy.objects.base import Base + obj = Base(id="some-id", applicationId="my-app") + obj["custom_prop"] = 42 # Add a dynamic property + obj["@detached_prop"] = another_object # Add a detached property + ``` + """ + id: Union[str, None] = None # totalChildrenCount: Union[int, None] = None applicationId: Union[str, None] = None diff --git a/src/specklepy/objects/data_objects.py b/src/specklepy/objects/data_objects.py index 73d7198..5c8fb06 100644 --- a/src/specklepy/objects/data_objects.py +++ b/src/specklepy/objects/data_objects.py @@ -13,6 +13,10 @@ class DataObject( speckle_type="Objects.Data.DataObject", detachable={"displayValue"}, ): + """ + A generic data object that can hold arbitrary properties and display values. + """ + name: str properties: Dict[str, object] displayValue: List[Base] diff --git a/src/specklepy/objects/geometry/arc.py b/src/specklepy/objects/geometry/arc.py index 64d1368..4609a75 100644 --- a/src/specklepy/objects/geometry/arc.py +++ b/src/specklepy/objects/geometry/arc.py @@ -10,15 +10,27 @@ from specklepy.objects.interfaces import ICurve, IHasUnits @dataclass(kw_only=True) class Arc(Base, IHasUnits, ICurve, speckle_type="Objects.Geometry.Arc"): """ + An arc defined by a plane, start point, mid point and end point. - attributes: - plane: asdfji;sfd - plane: asdfji;sfd - midPoint: ajosdfds - endPoint: ajosdfds + This class represents a circular arc in 3D space, defined by three points + and a plane. The arc is a portion of a circle that lies on the specified plane. - properties: - radius: asdfsadf + Attributes: + plane: The plane on which the arc lies + startPoint: The starting point of the arc + midPoint: A point on the arc between the start and end points + endPoint: The ending point of the arc. + + + ```py title="Example" + from specklepy.objects.geometry.plane import Plane + from specklepy.objects.geometry.point import Point + plane = Plane(origin=Point(0, 0, 0), normal=Point(0, 0, 1)) + start = Point(1, 0, 0) + mid = Point(0.7071, 0.7071, 0) + end = Point(0, 1, 0) + arc = Arc(plane=plane, startPoint=start, midPoint=mid, endPoint=end) + ``` """ plane: Plane @@ -28,10 +40,20 @@ class Arc(Base, IHasUnits, ICurve, speckle_type="Objects.Geometry.Arc"): @property def radius(self) -> float: + """Calculates the radius of the arc. + + Returns: + The radius of the arc, as the distance from the start point to the origin. + """ return self.startPoint.distance_to(self.plane.origin) @property def length(self) -> float: + """Calculates the length of the arc. + + Returns: + The length of the arc. + """ start_to_mid = self.startPoint.distance_to(self.midPoint) mid_to_end = self.midPoint.distance_to(self.endPoint) r = self.radius @@ -42,6 +64,11 @@ class Arc(Base, IHasUnits, ICurve, speckle_type="Objects.Geometry.Arc"): @property def measure(self) -> float: + """Calculates the angular measure of the arc in radians. + + Returns: + The angular measure of the arc in radians. + """ start_to_mid = self.startPoint.distance_to(self.midPoint) mid_to_end = self.midPoint.distance_to(self.endPoint) r = self.radius diff --git a/src/specklepy/objects/geometry/box.py b/src/specklepy/objects/geometry/box.py index 775a0d6..ab02b0b 100644 --- a/src/specklepy/objects/geometry/box.py +++ b/src/specklepy/objects/geometry/box.py @@ -9,7 +9,29 @@ from specklepy.objects.primitive import Interval @dataclass(kw_only=True) class Box(Base, IHasUnits, IHasArea, IHasVolume, speckle_type="Objects.Geometry.Box"): """ - a 3-dimensional box oriented on a plane + A 3-dimensional box oriented on a plane. + + This class represents a rectangular prism in 3D space, defined by a base plane and + three intervals specifying its dimensions along the x, y, and z axes. + + Attributes: + basePlane: The plane on which the box is oriented + xSize: The interval defining the box's size along the x-axis + ySize: The interval defining the box's size along the y-axis + zSize: The interval defining the box's size along the z-axis + + ```py title="Example" + from specklepy.objects.geometry.plane import Plane + from specklepy.objects.geometry.point import Point + from specklepy.objects.primitive import Interval + + base_plane = Plane(origin=Point(0, 0, 0), normal=Point(0, 0, 1)) + x_size = Interval(start=0, end=10) + y_size = Interval(start=0, end=5) + z_size = Interval(start=0, end=3) + + box = Box(basePlane=base_plane, xSize=x_size, ySize=y_size, zSize=z_size) + ``` """ basePlane: Plane @@ -29,6 +51,11 @@ class Box(Base, IHasUnits, IHasArea, IHasVolume, speckle_type="Objects.Geometry. @property def area(self) -> float: + """Calculates the surface area of the box. + + Returns: + The total surface area of the box. + """ return 2 * ( self.xSize.length * self.ySize.length + self.xSize.length * self.zSize.length @@ -37,4 +64,9 @@ class Box(Base, IHasUnits, IHasArea, IHasVolume, speckle_type="Objects.Geometry. @property def volume(self) -> float: + """Calculates the volume of the box. + + Returns: + The volume of the box. + """ return self.xSize.length * self.ySize.length * self.zSize.length