Updated tutorial docs.

neurobionics · Dec 19, 2024 · 81dece2 · 81dece2
1 parent 80a8186
commit 81dece2
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 79 deletions.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -80,20 +80,21 @@ pip install onshape-api
 Here's an example of making a simple GET request to list documents using the `onshape-api` library:
 
 ```python
-import onshape_api as osa
+from onshape_api.connect import Client
+from onshape_api.models.document import Document
 
 # Initialize the client
 client = osa.Client(
     env="./.env"
 )
 
 # Create a Document object from a URL
-doc = osa.Document.from_url(
+doc = Document.from_url(
     url="https://cad.onshape.com/documents/a1c1addf75444f54b504f25c/w/0d17b8ebb2a4c76be9fff3c7/e/a86aaf34d2f4353288df8812"
 )
 
 # Retrieve the assembly and its JSON representation
-assembly, assembly_json = client.get_assembly(
+assembly = client.get_assembly(
     did=doc.did,
     wtype=doc.wtype,
     wid=doc.wid,

diff --git a/docs/tutorials/edit.md b/docs/tutorials/edit.md
@@ -83,11 +83,13 @@ from onshape_api.parse import (
 assembly = client.get_assembly(doc.did, doc.wtype, doc.wid, elements["assembly"].id)
 
 # Extract components
-instances, id_to_name_map = get_instances(assembly)
-occurrences = get_occurrences(assembly, id_to_name_map)
-subassemblies = get_subassemblies(assembly, instances)
-parts = get_parts(assembly, client, instances)
-mates, relations = get_mates_and_relations(assembly, subassembly_map=subassemblies, id_to_name_map=id_to_name_map)
+instances, occurrences, id_to_name_map = get_instances(assemblymax_depth=1)
+
+subassemblies, rigid_subassemblies = get_subassemblies(assembly, client, instances)
+parts = get_parts(assembly, rigid_subassemblies, client, instances)
+
+mates, relations = get_mates_and_relations(assembly, subassemblies, rigid_subassemblies, id_to_name_map, parts)
+
 ```
 
 ---
@@ -97,11 +99,15 @@ mates, relations = get_mates_and_relations(assembly, subassembly_map=subassembli
 Generate a graph visualization of the assembly structure:
 
 ```python
-from onshape_api.graph import create_graph, plot_graph
+from onshape_api.graph import create_graph
+from onshape_api.urdf import get_robot
+from onshape_api.models.robot import Robot
 
 # Create and save the assembly graph
 graph, root_node = create_graph(occurrences=occurrences, instances=instances, parts=parts, mates=mates)
-plot_graph(graph, "bike.png")
+
+robot = get_robot(assembly, graph, root_node, parts, mates, relations, client, "test")
+robot.show_graph("bike.png")
 ```
 
 <img src="bike-graph.png" alt="Bike Graph" style="width: 100%;">
@@ -112,14 +118,9 @@ This will save an image of the assembly graph (`bike.png`) in your current worki
 
 ### Step 6: Export the Assembly to a URDF File
 
-Convert the assembly into a URDF file for robotics applications:
+Convert the robot class into a URDF file for robotics applications:
 
 ```python
-from onshape_api.urdf import get_robot
-from onshape_api.models.robot import Robot
-
-# Generate URDF links and joints
-robot = get_robot(assembly, graph, root_node, parts, mates, relations, client, "bike")
 robot.save("bike.urdf")
 ```
 

diff --git a/docs/tutorials/export.md b/docs/tutorials/export.md
@@ -15,114 +15,94 @@ Before you begin, ensure the following:
   pip install onshape-api
   ```
 - **API Keys**: Set up your Onshape API keys in a `.env` file. Refer to the [Getting Started](../getting-started.md) guide if needed.
-- **Document URL**: Have the URL of the Onshape assembly you want to convert. For this example, we’ll use:
-  <a href="https://cad.onshape.com/documents/00fdecd70b9459267a70825e/w/5b8859e00b5d129724548da1/e/8bb8553f756c40770e11d5b4" target="_blank">Arbor Press Assembly</a>.
+- **Document URL**: Have the URL of the Onshape assembly you want to export. For this example, we’ll use a quadruped robot assembly.
 
 ---
 
-## Workflow: Onshape Assembly to URDF
+## Workflow: Onshape Assembly to JSON and Graph Visualization
 
-### Step 1: Initialize the Client
+### Step 1: Set Up Logging and Initialize the Client
 
-Start by setting up the Onshape API client to authenticate and interact with your Onshape account:
+Start by configuring the logger and initializing the Onshape API client:
 
 ```python
-import os
-import onshape_api as osa
-from onshape_api.models.document import Document
+from onshape_api.connect import Client
+from onshape_api.log import LOGGER, LogLevel
 
-SCRIPT_DIRECTORY = os.path.dirname(os.path.realpath(__file__))
+LOGGER.set_file_name("ballbot.log")
+LOGGER.set_stream_level(LogLevel.INFO)
 
-client = osa.Client(
-    env="./.env"
-)
+client = Client(env="./.env")
 ```
 
+The logger will save logs to `ballbot.log` and display logs at the `INFO` level in the console.
+
 ---
 
 ### Step 2: Load the Onshape Assembly
 
-Use the assembly’s URL to load the document and fetch its details:
+Use the `Robot` class to load the assembly directly from its Onshape document URL:
 
 ```python
-# Replace with your Onshape assembly URL
-document = Document.from_url(
-    "https://cad.onshape.com/documents/00fdecd70b9459267a70825e/w/5b8859e00b5d129724548da1/e/8bb8553f756c40770e11d5b4"
-)
+from onshape_api.robot import Robot
 
-assembly = client.get_assembly(
-    did=document.did,
-    wtype=document.wtype,
-    wid=document.wid,
-    eid=document.eid,
-    with_meta_data=True,
+robot = Robot.from_url(
+    name="quadruped",
+    url="https://cad.onshape.com/documents/cf6b852d2c88d661ac2e17e8/w/c842455c29cc878dc48bdc68/e/b5e293d409dd0b88596181ef",
+    client=client,
+    max_depth=0,
+    use_user_defined_root=False,
 )
 ```
 
+This will create a `Robot` object named "quadruped" from the specified Onshape document URL. The `max_depth` parameter controls the level of subassemblies to include, and `use_user_defined_root` specifies whether to use a user-defined root for the assembly.
+
 ---
 
-### Step 3: Parse the Assembly Components
+### Step 3: Save the Assembly as JSON
 
-Extract instances, occurrences, parts, subassemblies, and relational data:
+Export the assembly data to a JSON file for easy analysis or integration with other tools:
 
 ```python
-instances, id_to_name_map = osa.get_instances(assembly)
-occurrences = osa.get_occurrences(assembly, id_to_name_map)
-parts = osa.get_parts(assembly, client, instances)
-subassemblies = osa.get_subassemblies(assembly, instances)
-mates, relations = osa.get_mates_and_relations(assembly, subassemblies, id_to_name_map)
+from onshape_api.utilities.helpers import save_model_as_json
+
+save_model_as_json(robot.assembly, "quadruped.json")
 ```
 
+This will save the assembly details into a file named `quadruped.json` in the current working directory.
+
 ---
 
 ### Step 4: Visualize the Assembly Graph
 
-Create and save a graph representation of the assembly’s structure:
+Generate and save a graphical representation of the assembly’s structure:
 
 ```python
-graph, root_node = osa.create_graph(
-    occurrences=occurrences,
-    instances=instances,
-    parts=parts,
-    mates=mates,
-)
-osa.plot_graph(graph, f"{assembly.document.name + '-' + assembly.name}.png")
+robot.show_graph(file_name="quadruped.png")
 ```
 
-This will save a PNG file of the assembly graph in your current working directory.
-
-<img src="assembly-graph.png" alt="Assembly Graph" style="width: 100%;">
+This will create a PNG file named `quadruped.png` showing the hierarchical structure of the assembly.
 
 ---
 
-### Step 5: Generate the URDF File
+### Step 5: Save the Robot Object as a URDF File
 
-Convert the parsed assembly data into a URDF file:
+If you plan to use the robot in a simulation environment, you can save the robot object as a URDF file:
 
 ```python
-robot = osa.get_robot(
-    assembly=assembly,
-    graph=graph,
-    root_node=root_node,
-    parts=parts,
-    mates=mates,
-    relations=relations,
-    client=client,
-    robot_name=f"{assembly.document.name + '-' + assembly.name}",
-)
-
-robot.save(f"{assembly.document.name + '-' + assembly.name}.urdf")
+robot.save()
 ```
 
-<img src="assembly-urdf.gif" alt="Assembly Graph" style="width: 100%;">
+This saves the robot object to disk as a URDF file named `quadruped.robot`.
 
 ---
 
 ## Result
 
-After running the script, you’ll find two files in your working directory:
+After running the script, you’ll find the following files in your working directory:
 
-1. A visual representation of the assembly graph (e.g., `document-name-assembly-name.png`).
-2. The URDF file (e.g., `document-name-assembly-name.urdf`).
+1. **Assembly JSON File** (`quadruped.json`): Contains the complete assembly details.
+2. **Assembly Graph** (`quadruped.png`): A visual representation of the assembly’s structure.
+3. **Robot URDF File** (`quadruped.urdf`): A URDF file for simulation.
 
-The URDF file can now be used in robotics simulators such as Gazebo or integrated with ROS.
+These files can be used for further analysis, simulation, or into other workflows.
diff --git a/examples/edit/main.py b/examples/edit/main.py
@@ -14,7 +14,9 @@
     LOGGER.set_file_name("edit.log")
     LOGGER.set_stream_level(LogLevel.INFO)
 
-    client = Client()
+    client = Client(
+        env="./.env",
+    )
     doc = Document.from_url(
         url="https://cad.onshape.com/documents/a1c1addf75444f54b504f25c/w/0d17b8ebb2a4c76be9fff3c7/e/a86aaf34d2f4353288df8812"
     )
@@ -29,7 +31,7 @@
     client.set_variables(doc.did, doc.wid, elements["variables"].id, variables)
     assembly = client.get_assembly(doc.did, doc.wtype, doc.wid, elements["assembly"].id)
 
-    instances, occurrences, id_to_name_map = get_instances(assembly, max_depth=0)
+    instances, occurrences, id_to_name_map = get_instances(assembly, max_depth=1)
 
     subassemblies, rigid_subassemblies = get_subassemblies(assembly, client, instances)
     parts = get_parts(assembly, rigid_subassemblies, client, instances)

diff --git a/examples/export/main.py b/examples/export/main.py
@@ -6,7 +6,7 @@
 if __name__ == "__main__":
     LOGGER.set_file_name("ballbot.log")
     LOGGER.set_stream_level(LogLevel.INFO)
-    client = Client()
+    client = Client(env="./.env")
 
     robot = Robot.from_url(
         name="quadruped",