docs(raycast.py): improve docstring formatting and move examples into…

… code blocks for better readability and consistency

camtools/raycast.py

@@ -27,12 +27,6 @@ def gen_rays(
         - pose is the camera-to-world transformation matrix
         - [X, Y, Z] is the ray direction in world coordinates
 
-    Example usage:
-        # Generate rays for all pixels in a 640x480 image
-        height, width = 480, 640
-        pixels = np.array([[x, y] for y in range(height) for x in range(width)])
-        centers, dirs = ct.raycast.gen_rays(K, T, pixels)
-
     Args:
         K: (3, 3) camera intrinsic matrix.
         T: (4, 4) camera extrinsic matrix (world-to-camera transformation).
@@ -42,6 +36,19 @@ def gen_rays(
         A tuple of (centers, dirs). All camera centers are identical since they
         originate from the same camera. The ray directions are in world
         coordinates and normalized to unit length.
+
+    Returns:
+        A tuple of (centers, dirs). All camera centers are identical since they
+        originate from the same camera. The ray directions are in world
+        coordinates and normalized to unit length.
+
+    Examples:
+        .. code-block:: python
+
+            # Generate rays for all pixels in a 640x480 image
+            height, width = 480, 640
+            pixels = np.array([[x, y] for y in range(height) for x in range(width)])
+            centers, dirs = ct.raycast.gen_rays(K, T, pixels)
     """
     sanity.assert_K(K)
     sanity.assert_T(T)
@@ -87,13 +94,6 @@ def mesh_to_im_distance(
     - P is the intersection point on the mesh surface
     - ||·|| denotes the Euclidean norm
 
-    Example usage:
-        # Create distance image for a 640x480 view
-        distance_image = ct.raycast.mesh_to_im_distance(mesh, K, T, 480, 640)
-        # Visualize distances
-        plt.imshow(distance_image)
-        plt.colorbar()
-
     Args:
         mesh: Open3D TriangleMesh to be ray casted.
         K: (3, 3) camera intrinsic matrix.
@@ -109,6 +109,14 @@ def mesh_to_im_distance(
     Note: For casting the same mesh with multiple camera views, use
     mesh_to_im_distances for better efficiency as it avoids repeated scene
     setup.
+
+    Examples:
+        .. code-block:: python
+
+            # Create distance image for a 640x480 view
+            distance_image = ct.raycast.mesh_to_im_distance(mesh, K, T, 480, 640)
+            plt.imshow(distance_image)
+            plt.colorbar()
     """
     im_distances = mesh_to_im_distances(
         mesh=mesh,
@@ -143,13 +151,6 @@ def mesh_to_im_distances(
     - P_i is the intersection point on the mesh surface for view i
     - ||·|| denotes the Euclidean norm
 
-    Example usage:
-        # Create distance images for 3 different views
-        distances = ct.raycast.mesh_to_im_distances(mesh, Ks, Ts, 480, 640)
-        # Visualize first view's distances
-        plt.imshow(distances[0])
-        plt.colorbar()
-
     Args:
         mesh: Open3D TriangleMesh to be ray casted.
         Ks: (N, 3, 3) array of camera intrinsic matrices for N views.
@@ -165,6 +166,16 @@ def mesh_to_im_distances(
 
     Note: This function is more efficient than calling mesh_to_im_distance
     multiple times as it only sets up the ray casting scene once.
+
+    Examples:
+        .. code-block:: python
+
+            # Create distance images for 3 different views
+            Ks = [K0, K1, K2]  # 3 intrinsic matrices
+            Ts = [T0, T1, T2]  # 3 extrinsic matrices
+            distances = ct.raycast.mesh_to_im_distances(mesh, Ks, Ts, 480, 640)
+            plt.imshow(distances[0])
+            plt.colorbar()
     """
     for K in Ks:
         sanity.assert_K(K)
@@ -215,13 +226,6 @@ def mesh_to_im_depth(
     - f is the focal length from the intrinsic matrix K
     - (u, v) are the pixel coordinates in the camera plane
 
-    Example usage:
-        # Create depth image for a 640x480 view
-        depth_image = ct.raycast.mesh_to_im_depth(mesh, K, T, 480, 640)
-        # Visualize depths
-        plt.imshow(depth_image)
-        plt.colorbar()
-
     Args:
         mesh: Open3D TriangleMesh to be ray casted.
         K: (3, 3) camera intrinsic matrix.
@@ -236,6 +240,14 @@ def mesh_to_im_depth(
 
     Note: This function internally uses mesh_to_im_distance and converts the
     distances to depths using the camera intrinsic parameters.
+
+    Examples:
+        .. code-block:: python
+
+            # Create depth image for a 640x480 view
+            im_depth = ct.raycast.mesh_to_im_depth(mesh, K, T, 480, 640)
+            plt.imshow(im_depth)
+            plt.colorbar()
     """
     im_distance = mesh_to_im_distance(mesh, K, T, height, width)
     im_depth = convert.im_distance_to_im_depth(im_distance, K)
@@ -262,13 +274,6 @@ def mesh_to_im_depths(
     - f is the focal length from the intrinsic matrix K
     - (u, v) are the pixel coordinates in the camera plane
 
-    Example usage:
-        # Create depth images for 3 different views
-        depths = ct.raycast.mesh_to_im_depths(mesh, Ks, Ts, 480, 640)
-        # Visualize first view's depths
-        plt.imshow(depths[0])
-        plt.colorbar()
-
     Args:
         mesh: Open3D TriangleMesh to be ray casted.
         Ks: (N, 3, 3) array of camera intrinsic matrices for N views.
@@ -284,6 +289,16 @@ def mesh_to_im_depths(
 
     Note: This function internally uses mesh_to_im_distances and converts the
     distances to depths using the camera intrinsic parameters.
+
+    Examples:
+        .. code-block:: python
+
+            # Create depth images for 3 different views
+            Ks = [K0, K1, K2]  # 3 intrinsic matrices
+            Ts = [T0, T1, T2]  # 3 extrinsic matrices
+            im_depths = ct.raycast.mesh_to_im_depths(mesh, Ks, Ts, 480, 640)
+            plt.imshow(im_depths[0])
+            plt.colorbar()
     """
     im_distances = mesh_to_im_distances(mesh, Ks, Ts, height, width)
     im_depths = np.stack(
@@ -310,12 +325,6 @@ def mesh_to_im_mask(
     do not (background). Foreground pixels are set to 1.0 and background pixels
     are set to 0.0.
 
-    Example usage:
-        # Create mask image for a 640x480 view
-        mask = ct.raycast.mesh_to_im_mask(mesh, K, T, 480, 640)
-        # Visualize mask
-        plt.imshow(mask, cmap='gray')
-
     Args:
         mesh: Open3D TriangleMesh to be ray casted.
         K: (3, 3) camera intrinsic matrix.
@@ -331,6 +340,13 @@ def mesh_to_im_mask(
     Note: This function is not optimized for repeated use with the same mesh.
     For multiple ray casts with the same mesh, create the ray casting scene
     manually for better performance.
+
+    Examples:
+        .. code-block:: python
+
+            # Create mask image for a 640x480 view
+            mask = ct.raycast.mesh_to_im_mask(mesh, K, T, 480, 640)
+            plt.imshow(mask, cmap='gray')
     """
     im_distance = mesh_to_im_distance(mesh, K, T, height, width)
     im_mask = (im_distance != np.inf).astype(np.float32)