Merge pull request #1378 from compas-dev/conversions-api

Explicit methods for geometry and separate methods for doc objects

CHANGELOG.md

@@ -32,6 +32,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added `compas.geometry.curves.curve.Curve.from_native`.
 * Added `compas_rhino.geometry.curves.curve.Curve.from_native`.
 * Added `compas_rhino.geometry.curves.nurbs.NurbsCurve.from_native`.
+* Added `compas_rhino.conversions.breps.brep_to_compas_mesh`.
+* Added `compas_rhino.conversions.docobjects.brepobject_to_compas`.
+* Added `compas_rhino.conversions.docobjects.curveobject_to_compas`.
+* Added `compas_rhino.conversions.docobjects.meshobject_to_compas`.
+* Added `compas_rhino.conversions.docobjects.pointobject_to_compas`.
 * Added `compas.datastructures.HashTree` and `compas.datastructures.HashNode`.
 
 ### Changed
@@ -47,7 +52,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Changed `compas.geometry.curves.nurbs.NurbsCurve.__new__` to prevent instantiation of `NurbsCurve` directly.
 * Changed `compas_rhino.geometry.curves.new_nurbscurve_from_...` to `nurbscurve_from_...`.
 * Fixed `compas_ghpython` Grasshopper components not included in published pakcage.
-* Chnaged `compas.colors.Color.coerce` to take color as is, if it is already aninstance of `compas.colors.Color`.
+* Changed `compas.colors.Color.coerce` to take color as is, if it is already an instance of `compas.colors.Color`.
+* Changed `compas_rhino.conversions.surfaces.surface_to_compas` to work only with surface geometry.
+* Changed `compas_rhino.conversions.curves.curve_to_compas_line` to work only with geometry.
+* Changed `compas_rhino.conversions.curves.curve_to_compas_circle` to work only with geometry.
+* Changed `compas_rhino.conversions.curves.curve_to_compas_ellipse` to work only with geometry.
+* Changed `compas_rhino.conversions.curves.curve_to_compas_polyline` to work only with geometry.
+* Changed `compas_rhino.objects.get_point_coordinates` to deprecated (removed in v2.3).
+* Changed `compas_rhino.objects.get_line_coordinates` to deprecated (removed in v2.3).
+* Changed `compas_rhino.objects.get_polyline_coordinates` to deprecated (removed in v2.3).
+* Changed `compas_rhino.objects.get_polygon_coordinates` to deprecated (removed in v2.3).
 * Fixed a bug in `worldtransformation` of `compas.scene.SceneObject` to include the object's own frame.
 
 ### Removed
@@ -77,6 +91,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Removed `compas.geometry.curves.curve.new_nurbscurve`.
 * Removed `compas_rhino.geometry.curves.new_curve`.
 * Removed `compas_rhino.geometry.curves.new_nurbscurve`.
+* Removed `compas_rhino.conversions.surfaces.data_to_rhino_surface`.
+* Removed `compas_rhino.conversions.surfaces.surface_to_compas_data`.
+* Removed `compas_rhino.conversions.surfaces.surface_to_compas_quadmesh`.
+* Removed `compas_rhino.conversions.curves.curve_to_compas_data`.
 
 ## [2.2.1] 2024-06-25
 
@@ -88,7 +106,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
-
 ## [2.2.0] 2024-06-24
 
 ### Added

docs/userguide/cad.rhino.rst

@@ -88,10 +88,183 @@ For more information on visualisation scenes, see :doc:`/userguide/basics.visual
 Conversions
 ===========
 
+For conversion between Rhino objects and COMPAS objects, different scenarios exist.
+
+Rhino Geometry to COMPAS
+------------------------
+
+Conversions of geometry is straightforward and explicit.
+
+.. code-block:: python
+
+    import Rhino.Geometry
+    import compas_rhino.conversions
+
+    point = Rhino.Geometry.Point3d(...)
+    point = compas_rhino.conversions.point_to_compas(point)
+
+    line = Rhino.Geometry.Line(...)
+    line = compas_rhino.conversions.line_to_compas(line)
+
+    plane = Rhino.Geometry.Plane(...)
+    plane = compas_rhino.conversions.plane_to_compas(plane)
+
+    box = Rhino.Geometry.Box(...)
+    box = compas_rhino.conversions.box_to_compas(box)
+
+    mesh = Rhino.Geometry.Mesh(...)
+    mesh = compas_rhino.conversions.mesh_to_compas(mesh)
+
+    curve = Rhino.Geometry.Curve(...)
+    curve = compas_rhino.conversions.curve_to_compas(curve)
+
+    surface = Rhino.Geometry.Surface(...)
+    surface = compas_rhino.conversions.surface_to_compas(surface)
+
+    brep = Rhino.Geometry.Brep(...)
+    brep = compas_rhino.conversions.brep_to_compas(brep)
+
+
+Note that Rhino doen't distinguish between a frame and a plane.
+Therefore, to convert `Rhino.Geometry.Plane` to :class:`compas.geometry.Frame`.
+
+.. code-block:: python
+
+    plane = Rhino.Geometry.Plane(...)
+    frame = compas_rhino.conversions.plane_to_compas_frame(plane)
+
+
+Rhino Object to COMPAS
+----------------------
+
+A Rhino Document contains Rhino Object instead of Rhino Geometry.
+The geometry of a Rhino Object is stored in the corresponding attribute (`obj.Geometry`).
+
+Converting point, curve, and mesh objects is straightforward.
+
+.. code-block:: python
+
+    import compas_rhino.objects
+    import compas_rhino.conversions
+
+    guid = compas_rhino.objects.select_point()
+    point = compas_rhino.conversions.pointobject_to_compas(guid)
+
+    guid = compas_rhino.objects.select_curve()
+    curve = compas_rhino.conversions.curveobject_to_compas(guid)
+
+    guid = compas_rhino.objects.select_mesh()
+    mesh = compas_rhino.conversions.meshobject_to_compas(guid)
+
+
+In the case of curve objects, note that the conversion function will return a NurbsCurve in almost all cases.
+If the curve has a specific geometry, it can be converted explicitly using the corresponding geomtry conversion function.
+For example, if the curve is a circle.
+
+.. code-block:: python
+
+    import compas_rhino.objects
+    import compas_rhino.conversions
+
+    guid = compas_rhino.objects.select_curve()
+    obj = compas_rhino.objects.find_object(guid)
+
+    circle = compas_rhino.conversions.curve_to_compas_circle(obj.Geometry)
+
+
+In the case of all other objects, conversions are a bit trickier.
+This is because in a Rhino Document, almost all other geometries are represented by a BrepObject regardless of the actual geometry type.
+For example, when you add a sphere to a model, the DocObject is a BrepObject, and the geometry of the object is a Brep.
+Therefore, conversions of other objects have to be done more carefully.
+
+.. code-block:: python
+
+    import compas_rhino.objects
+    import compas_rhino.conversions
+
+    guid = compas_rhino.objects.select_object()
+    brep = compas_rhino.conversions.brepobject_to_compas(guid)
+
+
+Also here, if the object is (supposed to be) a specific type of geometry,
+conversion can be done more explicitly using the geometry conversion functions instead.
+For example, if the geometry of the object is a Rhino Cylinder.
+
+.. code-block:: python
+
+    import compas_rhino.objects
+    import compas_rhino.conversions
+
+    guid = compas_rhino.objects.select_object()
+    obj = compas_rhino.objects.find_object(guid)
+
+    cylinder = compas_rhino.conversions.brep_to_compas_cylinder(obj.Geometry)
+
+
+COMPAS to Rhino Geometry
+------------------------
+
+.. code-block:: python
+
+    import compas.geometry
+    import compas_rhino.conversions
+
+    point = compas.geometry.Point(...)
+    point = compas_rhino.conversions.point_to_rhino(point)
+
+    line = compas.geometry.Line(...)
+    line = compas_rhino.conversions.line_to_rhino(line)
+
+    plane = compas.geometry.Plane(...)
+    plane = compas_rhino.conversions.plane_to_rhino(plane)
+
+    box = compas.geometry.Box(...)
+    box = compas_rhino.conversions.box_to_rhino(box)
+
+    curve = compas.geometry.Curve(...)
+    curve = compas_rhino.conversions.curve_to_rhino(curve)
+
+    surface = compas.geometry.Surface(...)
+    surface = compas_rhino.conversions.surface_to_rhino(surface)
+
+    brep = compas.geometry.Brep(...)
+    brep = compas_rhino.conversions.brep_to_rhino(brep)
+
+
+To convert a :class:`compas.geometry.Frame`.
+
+.. code-block:: python
+
+    frame = compas.geometry.Frame(...)
+    plane = compas_rhino.conversions.frame_to_rhino_plane(frame)
+
+
+COMPAS to Rhino Object
+----------------------
+
+COMPAS objects are converted to Rhino Objects implicitly, by placing them into a visualisation scene.
+However, you can create a Rhino Object in a Rhino Dcocument explicitly from a COMPAS object.
+
+.. code-block:: python
+
+    import scriptcontext as sc
+    import compas.geometry 
+    import compas_rhino_conversions
+
+    point = compas.geometry.Point(...)
+    geometry = compas_rhino.conversions.point_to_rhino(point)
+
+    guid = sc.doc.Objects.AddPoint(geometry)
+
 
 Data Exchange
 =============
 
+JSON
+----
+
+rhino3dm
+--------
 
 Remote Procedure Calls
 ======================

src/compas_rhino/conversions/__init__.py

@@ -43,11 +43,8 @@
 )
 from .surfaces import (
     surface_to_rhino,
-    data_to_rhino_surface,
-    surface_to_compas_data,
     surface_to_compas,
     surface_to_compas_mesh,
-    surface_to_compas_quadmesh,
 )
 from .shapes import (
     box_to_rhino,
@@ -73,10 +70,12 @@
 )
 from .breps import (
     brep_to_rhino,
+    brep_to_compas,
     brep_to_compas_box,
     brep_to_compas_cone,
     brep_to_compas_cylinder,
     brep_to_compas_sphere,
+    brep_to_compas_mesh,
 )
 from .extrusions import (
     extrusion_to_compas_box,
@@ -89,6 +88,13 @@
     transformation_matrix_to_rhino,
 )
 
+from .docobjects import (
+    brepobject_to_compas,
+    curveobject_to_compas,
+    meshobject_to_compas,
+    pointobject_to_compas,
+)
+
 
 __all__ = [
     "ConversionError",
@@ -127,11 +133,8 @@
     "curve_to_compas",
     # surfaces
     "surface_to_rhino",
-    "surface_to_compas_data",
-    "data_to_rhino_surface",
     "surface_to_compas",
     "surface_to_compas_mesh",
-    "surface_to_compas_quadmesh",
     # shapes
     "box_to_rhino",
     "sphere_to_rhino",
@@ -154,15 +157,22 @@
     "mesh_to_compas",
     # breps
     "brep_to_rhino",
+    "brep_to_compas",
     "brep_to_compas_box",
     "brep_to_compas_cone",
     "brep_to_compas_cylinder",
     "brep_to_compas_sphere",
+    "brep_to_compas_mesh",
     # extrusions
     "extrusion_to_compas_box",
     "extrusion_to_compas_cylinder",
     "extrusion_to_compas_torus",
     # transformations
     "transformation_to_rhino",
     "transformation_matrix_to_rhino",
+    # docobjects
+    "brepobject_to_compas",
+    "curveobject_to_compas",
+    "meshobject_to_compas",
+    "pointobject_to_compas",
 ]