TurtleGL-3d 1.2.4__tar.gz → 1.2.7__tar.gz

turtlegl_3d-1.2.7/PKG-INFO

@@ -0,0 +1,700 @@
+Metadata-Version: 2.4
+Name: TurtleGL-3d
+Version: 1.2.7
+Summary: A 3D grafics library based on turtle
+Home-page: https://github.com/MichaelHyan/turtleGL
+Author: Han Yan
+Author-email: Han Yan <3367461801@qq.com>
+License: 
+                                         Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://github.com/MichaelHyan/turtleGL
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.4
+Requires-Dist: opencv-python>=4.12.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# 🐢 TurtleGL-3d
+
+**A 3D graphics library based on Python turtle and OpenGL-style rendering techniques.**
+
+An object-oriented, intuitive Python 3D graphics library based on the turtle library.
+
+---
+
+## ✨ Features
+
+- 🎥 **Camera System** — Independent camera object supporting perspective / cabinet / isometric / orthographic projection modes.
+- 🎨 **Scene Management** — Structured scene object supporting line, face, and texture data management.
+- 📐 **3D Function Plotting** — 3D function image plotting based on `plot3d` object.
+- 📦 **Volume Calculation** — Ray method volume calculation supporting multi-directional checks and partitioning acceleration.
+- 🖼️ **Texture Mapping** — Homography matrix-based texture mapping.
+- 🌗 **Shading & Normal** — Three rendering modes: material preview / shadow mode / normal preview.
+- 📁 **OBJ Import** — Support for importing `.obj` 3D models with normal correction.
+- 🎬 **Image & Video Export** — OpenCV-based image export and video compositing.
+- 🔄 **Transform** — Spatial transformations: rotation, translation, scaling, etc.
+- 📊 **Depth Sorting** — Depth sorting algorithms for different projection modes.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install TurtleGL-3d
+```
+
+### Dependencies
+
+- Python >= 3.8
+- numpy >= 1.24.4
+- opencv-python >= 4.12.0
+
+---
+
+## 🚀 Quick Start
+
+### Basic Example: Drawing a Colorful Cube
+
+```python
+import turtleGL
+
+# Instantiate the camera
+camera = turtleGL.camera()
+camera.camera_position = [100, 100, 100]
+camera.to_target([0, 0, 0])       # Face the origin
+camera.camera_focal = 300          # Focal length
+camera.type = 1                    # Perspective mode
+camera.rend = 1                    # Shadow mode
+
+# Instantiate the scene
+scene = turtleGL.scene()
+scene.face = [
+    [[[50, 50, 0], [-50, 50, 0], [-50, -50, 0], [50, -50, 0]], '#FF0000'],
+    [[[50, 50, 100], [-50, 50, 100], [-50, -50, 100], [50, -50, 100]], '#00FF00'],
+    [[[50, 50, 0], [50, 50, 100], [50, -50, 100], [50, -50, 0]], '#0000FF'],
+    [[[-50, 50, 0], [-50, -50, 0], [-50, -50, 100], [-50, 50, 100]], '#FFFF00'],
+    [[[50, 50, 0], [-50, 50, 0], [-50, 50, 100], [50, 50, 100]], '#FF00FF'],
+    [[[-50, -50, 0], [50, -50, 0], [50, -50, 100], [-50, -50, 100]], '#00FFFF'],
+]
+
+# Depth sorting and drawing
+camera.draw_from_scene(scene.sort_all_avg(camera.camera_position))
+camera.done()
+```
+
+### Importing an OBJ Model
+
+```python
+import turtleGL, math
+
+camera = turtleGL.camera('OBJ Example')
+camera.camera_position = [-101, -121, -150]
+camera.to_target([0, 0, 50])
+camera.camera_focal = 500
+camera.ray = [1, 1, -1]
+camera.type = 1
+camera.rend = 1
+
+scene = turtleGL.scene()
+scene.import_obj('model.obj', 50, '#66ccff')  # Scale 50x, specify color
+scene.check_obj_norm('model.obj')              # Correct normals
+scene.generate_line('#ffffff')                  # Generate edges
+
+# Rotation animation
+for i in range(360):
+    camera.clear()
+    camera.camera_position = [150 * math.cos(math.radians(i)),
+                               150 * math.sin(math.radians(i)),
+                               150]
+    camera.to_target([0, 0, 0])
+    camera.draw_from_scene(scene.sort_all_avg(camera.camera_position))
+    camera.update()
+```
+
+### 3D Function Plotting
+
+```python
+import turtleGL
+
+camera = turtleGL.camera('Plot3D Example')
+camera.type = 0  # Cabinet mode
+
+scene = turtleGL.plot3d()
+scene.xlim = [-100, 100]
+scene.ylim = [-100, 100]
+scene.step = 10
+
+def function(x, y):
+    return 0.01 * (x**2 - y**2)
+
+scene.generate_face(function)
+scene.generate_line(function, color='#000000')
+camera.draw_from_scene(scene.sort_all_cabin())
+camera.done()
+```
+
+### Volume Calculation
+
+```python
+import turtleGL
+
+camera = turtleGL.camera()
+camera.camera_position = [10, 120, 10]
+camera.to_target([0, 0, 0])
+camera.camera_focal = 500
+camera.type = 1
+camera.rend = 1
+
+scene = turtleGL.scene()
+scene.import_obj('model.obj', 50, '#66ccff')
+scene.check_obj_norm('model.obj')
+scene.triangulation()       # Triangulation is required for volume calculation
+scene.generate_line('#ff0000')
+
+volume = turtleGL.volume()
+volume.sample_distance = 5   # Sampling distance
+volume.check = True          # Multi-directional check
+volume.allow_edge = True     # Allow edge intersections
+volume.volume(scene.face)    # Calculate volume
+
+camera.draw_from_scene(scene.sort_line_avg(camera.camera_position))
+for i in volume.points:
+    camera.dot(i)
+camera.done()
+```
+
+### Texture Mapping & Image Export
+
+```python
+import turtleGL
+
+camera = turtleGL.camera('Texture Example')
+camera.camera_position = [201, 201, 131]
+camera.to_target([0, 0, 50])
+camera.camera_focal = 500
+camera.type = 1
+camera.rend = 1
+
+scene = turtleGL.scene()
+scene.tex = [
+    [[[50, 50, 100], [-50, 50, 100], [-50, -50, 100], [50, -50, 100]], 'grass_up.png'],
+    [[[50, 50, 0], [-50, 50, 0], [-50, -50, 0], [50, -50, 0]], 'grass_bottom.png'],
+]
+
+# Render and export using OpenCV
+camera.image_size = [700, 700]
+camera.create_image('#ffffff')
+camera.draw_from_scene_cv2(scene.sort_all_avg(camera.camera_position))
+camera.imshow()       # Display
+camera.imwrite('output.png')  # Save image
+```
+
+---
+
+## 📖 API Reference
+
+### Camera Object
+
+The camera object handles 3D to 2D projection and rendering.
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `camera_position` | `[x,y,z]` | `[0,0,0]` | Camera position |
+| `camera_direction` | `[x,y,z]` | `[0,0,1]` | Camera look direction |
+| `camera_rotation` | `float` | `0` | Camera rotation angle (radians), causing left/right tilt |
+| `camera_focal` | `float` | `1` | Focal length |
+| `point_behind_cam_type` | `int` | `0` | Handling method for points behind the camera (0/1/2/3) |
+| `point_behind_cam_allow_count` | `int` | `0` | Number of allowed behind-camera points during material rendering |
+| `ray` | `[x,y,z]` | `[0,0,-1]` | Light direction, used for shading |
+| `rend` | `int` | `0` | Rendering type: 0 material preview / 1 shadow mode / 2 normal preview |
+| `shade_value` | `int` | `128` | Multiply factor for shading (0-255) |
+| `pensize` | `int` | `2` | Pen size (only affects lines) |
+| `pencolor` | `str` | `'#000000'` | Pen color (only affects lines) |
+| `type` | `int` | `1` | Camera type: 0 cabinet / 1 perspective / 2 isometric / -1 orthographic |
+| `grating_size` | `[x,y]` | `[500,400]` | Raster rendering area size |
+| `grating_length` | `int` | `1` | Raster sampling step |
+| `image_size` | `[x,y]` | `[500,400]` | Export image size |
+| `image` | `ndarray` | `[]` | Currently stored OpenCV image |
+
+#### Handling Points Behind the Camera
+
+| Mode | Description |
+|------|-------------|
+| `0` | No processing; points behind the camera appear in the opposite direction |
+| `1` | Flip UV to bring points back to normal orientation |
+| `2` | Use orthographic mode with small deviation |
+| `3` | Use scaled orthographic perspective |
+
+#### Rendering Modes
+
+| Mode | Description |
+|------|-------------|
+| `0` — Material Preview | Faces display the specified color directly |
+| `1` — Shadow Mode | Shadows calculated based on angle between light direction and normal; backlit faces use the multiply factor |
+| `2` — Normal Mode | Normal direction cosine relative to camera direction > 0 displays blue, otherwise red |
+
+#### Methods
+
+```python
+# Basic Setup
+setposition([x,y,z])          # Set camera position
+setdirection([x,y,z])         # Set camera direction
+setfocal(x)                   # Set focal length
+settype(x)                    # Set projection type (supports 'focal'/'cabin'/'isometric')
+to_target([x,y,z])            # Point camera toward target
+status()                      # Print current camera attributes
+
+# Coordinate Mapping
+pointfocal([x,y,z])           # Perspective: 3D → 2D mapping, returns [[u,v], bool]
+pointcabinet([x,y,z])         # Cabinet: 3D → 2D mapping
+pointisometric([x,y,z])       # Isometric: 3D → 2D mapping
+pointorthografic([x,y,z])     # Orthographic: 3D → 2D mapping
+pointfocal_inverse([u,v])     # Perspective: 2D → 3D inverse mapping
+
+# Drawing (turtle rendering)
+dot([x,y,z], color)           # Draw a single point
+drawline(linedata)            # Draw an edge
+drawface(facedata)            # Draw a face
+drawtex(facedata)             # Draw texture
+draw_from_scene(scenedata)    # Draw integrated data
+draw_axis(l)                  # Draw coordinate axes
+write(point, str)             # Write text at a 3D position
+
+# Drawing (OpenCV rendering)
+drawline_cv2(linedata)        # Draw edge with OpenCV
+drawface_cv2(facedata)        # Draw face with OpenCV
+drawtex_cv2(facedata)         # Draw texture with OpenCV
+draw_from_scene_cv2(scenedata)# Draw integrated data with OpenCV
+
+# Image Export
+create_image(bgcolor)         # Initialize image (can be called repeatedly to clear)
+imshow()                      # Display current image
+imwrite(path)                 # Save image to file
+capture(path, index)          # Capture frame by index (for video frames)
+to_video(path, fps=30)        # Compose video
+
+# Raster Algorithm (experimental)
+grating(face)                 # Perform raster calculation
+grating_cv2(face)             # Raster with OpenCV
+show_grating_limit()          # Show rendering area border
+
+# Utilities
+tracer(t)                     # Control animation switch
+delay()                       # Delay
+clear()                       # Clear canvas
+bgcolor(color)                # Set background color
+update()                      # Update canvas
+done()                        # Prevent window from closing automatically
+```
+
+---
+
+### Scene Object
+
+The scene object stores line, face, and texture data, and supports spatial transformations and depth sorting.
+
+#### Data Format
+
+```python
+# Edge data
+[[[x1,y1,z1], [x2,y2,z2]], '#RRGGBB']
+
+# Face data (enter vertices in counterclockwise order; normal points outward)
+[[[x1,y1,z1], [x2,y2,z2], ..., [xn,yn,zn]], '#RRGGBB']
+
+# Texture data (4 vertices, color replaced by image path)
+[[[x1,y1,z1], [x2,y2,z2], [x3,y3,z3], [x4,y4,z4]], 'texture.png']
+```
+
+#### Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `line` | List of edge data |
+| `face` | List of face data |
+| `tex` | List of texture data |
+| `center` | Center point of the scene |
+
+#### Methods
+
+```python
+# Add Data
+addline([[x1,y1,z1],[x2,y2,z2],'#color'])   # Add an edge
+addface([[x1,y1,z1],...,[xn,yn,zn],'#color'])# Add a face
+
+# Import/Export
+import_line(path)              # Import line data (CSV)
+import_face(path)              # Import face data (CSV)
+export_line(path)              # Export line data (CSV)
+export_face(path)              # Export face data (CSV)
+
+# OBJ Model
+import_obj(path, scale, color) # Import OBJ model (random color if color is empty)
+import_obj_normal(path)        # Import OBJ normal data
+check_obj_norm(path)           # Correct face orientation based on normals
+add_obj(filepath, scale, color)# Import OBJ and append to existing face data
+
+# Spatial Transformations
+rotate(rotate_vector, center)  # Rotate around center (rotation vector in radians)
+move(move_vector)              # Translate
+scale(scale_vector, center)    # Scale
+rotate_edge()                  # Cycle edges (change triangulation partition)
+
+# Depth Sorting — Perspective/Orthographic Modes
+sort_line_avg(camera_pos)      # Sort edges (modifies object attribute and returns)
+sort_face_avg(camera_pos)      # Sort faces
+sort_tex_avg(camera_pos)       # Sort textures
+sort_all_avg(camera_pos)       # Sort all (returns data without modifying object)
+
+# Depth Sorting — Cabinet Mode
+sort_line_cabin()              # Sort edges
+sort_face_cabin()              # Sort faces
+sort_tex_cabin()               # Sort textures
+sort_all_cabin()               # Sort all
+
+# Depth Sorting — Isometric Mode
+sort_line_isometric()          # Sort edges
+sort_face_isometric()          # Sort faces
+sort_tex_isometric()           # Sort textures
+sort_all_isometric()           # Sort all
+
+# Other
+reverse_normvect(i)            # Reverse normal direction of the i-th face
+generate_line(color)           # Generate edges from face data
+triangulation()                # Triangulate faces
+get_center()                   # Calculate and return the scene center point
+```
+
+---
+
+### Plot3D Object
+
+Object for drawing 3D function graphs, similar to Scene but data generation depends on the target function.
+
+#### Attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `xlim` | `[-10, 10]` | X domain |
+| `ylim` | `[-10, 10]` | Y domain |
+| `step` | `1` | Sampling step |
+| `line` | `[]` | Edge data |
+| `face` | `[]` | Face data |
+| `center` | `[0,0,0]` | Center point |
+
+#### Methods
+
+```python
+generate_face(func, color=True)  # Generate face data for the function (auto color by height)
+generate_line(func, color)       # Generate edge data for the function
+rotate(rotate_vector, center)    # Rotate
+move(move_vector)                # Translate
+scale(scale_vector, center)      # Scale
+# Same depth sorting methods as Scene
+```
+
+---
+
+### Volume Object
+
+Volume calculation object using ray casting to determine if a point is inside a closed triangular mesh.
+
+#### Attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `points` | `[]` | List of interior points after calculation |
+| `sample_distance` | `1` | Sampling grid spacing |
+| `grid_limit` | `inf` | Threshold for enabling partitioning acceleration (triangle count) |
+| `check` | `True` | Enable multi-directional check |
+| `allow_edge` | `True` | Allow counting edge intersections |
+
+#### Methods
+
+```python
+volume(scene_face_data)  # Calculate volume, return all interior points
+```
+
+> ⚠️ The partitioning acceleration (`grid_limit`) is only recommended for convex polyhedra; irregular shapes may produce erroneous results.
+
+---
+
+## 🧪 Experimental: Rasterization
+
+Raster algorithm is experimental and not yet stable.
+
+```python
+scene.triangulation()             # Triangulate faces (raster mode only supports triangles)
+camera.grating_size = [500, 400]  # Set rendering area size
+camera.show_grating_limit()       # Show rendering area border
+camera.grating(face)              # Execute raster calculation
+```
+
+In rendering mode `rend=1`, raster mode does not use shadow calculation but computes the light path.
+
+---
+
+## 🎬 Image & Video Export
+
+Since turtle itself does not support image capture, the library provides OpenCV-based image/video export:
+
+```python
+# Initialization
+camera.image_size = [500, 400]
+camera.create_image('#ffffff')    # Create image (can be called repeatedly to clear)
+
+# Rendering
+camera.draw_from_scene_cv2(scene_data)  # Render with OpenCV
+
+# Export
+camera.imwrite('output.png')     # Save image
+
+# Video creation
+camera.capture('frames', i)      # Save frames by index → ./frames/00000001.png
+camera.to_video('frames')        # Compose video → frames.mp4
+```
+
+---
+
+## 📁 Project Structure
+
+```
+turtleGL-3d/
+├── pyproject.toml
+├── setup.py
+├── LICENSE
+├── README.md
+├── README_zh.md
+└── src/
+    └── turtleGL/
+        ├── __init__.py
+        ├── src/
+        │   ├── camera.py      # Camera object
+        │   ├── scene.py       # Scene object
+        │   ├── plot3d.py      # 3D function plot object
+        │   └── volume.py      # Volume calculation object
+        └── example/
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🔗 Links
+
+- **Homepage**: [https://github.com/MichaelHyan/turtleGL](https://github.com/MichaelHyan/turtleGL)
+- **PyPI**: [https://pypi.org/project/TurtleGL-3d/](https://pypi.org/project/TurtleGL-3d/)