Skip to content

Latest commit

 

History

History
158 lines (110 loc) · 10.7 KB

readme.md

File metadata and controls

158 lines (110 loc) · 10.7 KB
Raw

Portal.GH

GitHub Release Static Badge GitHub License

Portal is a Grasshopper3D plugin designed to facilitate Inter-Process Communication (IPC), enabling seamless data exchange between Grasshopper and external applications or processes. By extending workflow capabilities beyond Grasshopper3D and Rhino3D, Portal opens up new possibilities for integrated, multi-platform design processes.

⭐️ Like this repo? please consider a star!

🔌Adaptors

  • Portal.blender
  • Portal.unity (Coming Soon)
  • Portal.revit (Coming Soon)
blender-grasshopper-link-0.3.1-30sec.mp4

🌟 Features

  • Multiple Communication Methods:
    • UDP Sockets
    • WebSockets
    • Named Pipes
    • Memory Mapped File
    • Local File
  • Geometry Serialization / Deserialization :
    • Point
    • Mesh
      • UV Coordinates
      • Vertex colors
    • Curve (PolylineCurve, ArcCurve, LineCurve, NurbsCurve)
  • Viewport Camera Serialization
  • Referenced Object Serialization
    • Layer full path
    • Layer / Object material and texture
  • Data Compression / Decompression using GZip
  • Metadata Support for geometry

Note

Due to the fact that I am working on this project alone in my free time, the development process maybe slow. I will try to implement features as soon as possible. If you have any feature requests, please let me know by creating a feature request.

🗺️ Roadmap

0.5.0:

  • base64 encoding / decoding
  • More material properties (transparency, roughness, etc.)
  • feature request are welcome.

🛠️ System Requirements

  • Rhino3D 7.13+
  • Windows OS

📥 Installation

  1. Download the Portal.Gh.zip from the Releases page.
  2. Unzip and copy the Portal.GH folder into ...\AppData\Roaming\Grasshopper\Libraries
  3. Unblock all library files:
    • Right-click on each .gha and .dll file
    • If there's an "Unblock" option, make sure to select it

🔌 Communication Methods

Portal supports various communication methods, each with its own strengths and drawbacks. The choice of method depends on the specific requirements of your workflow, such as speed, reliability, and whether the communication is local or remote.

⭐ Recommended methods for most use cases.

Method Speed Reliability Remote Streamable Description
⭐WebSockets 5/10 9/10 ✅ ✅ Websockets provide a stable connection capable of handling large payloads, ideal for large, content-critical data that requires cross-machine communication over a network, but can also support local communication, although not as efficiently as Named Pipes.
UDP Sockets 6/10 7/10 ✅ ❌ UDP offers fast, connectionless transmission, ideal for payloads under 1472 bytes requiring quick, straightforward transmission without connection setup or integrity checks (e.g., sending small instructions), and supports cross-machine communication; however, it is not suitable for payloads over 1472 bytes as data may become corrupted due to fragmentation.
⭐Named Pipes 8/10 10/10 ❌ ✅ Named Pipes enable unidirectional communication through a pipe, suitable for fast, reliable, and ordered byte-stream-based data transfer. Limited to the local machine.
Memory Mapped File 10/10 6/10 ❌ ❌ Memory-Mapped Files map a portion of memory to the address space of a process for efficient inter-process communication, ideal for extremely fast read and write operations directly in shared memory; however, they are limited to the local machine and may cause data corruption, memory leaks, or program crashes if not handled properly.
Local File I/O 1/10 2/10 ❌ ❌ File I/O operations allow reading from and writing to files on a storage device, suitable for scenarios requiring persistent storage of data; however, they are limited to the local machine and can be slow compared to memory and network operations.

⌛Example Workflow

Here's an example of how you might send a mesh from Grasshopper to another application (e.g., Blender):

  1. In Grasshopper:

    • Serialize the mesh into JSON
    • Encode the JSON text into bytes
    • Compress the bytes using GZip
    • Send the compressed data via Named Pipe

  2. In the receiving application (e.g., Blender):

    • Receive the compressed bytes
    • Decompress the data
    • Decode the bytes into a string
    • Parse the JSON
    • Deserialize and construct the mesh

⚒️ For Developer

Data Format

  • All data is sent and received as bytes.
  • Data can be compressed using GZip before sending to save bandwidth and increase transfer speed. Proper decompression handling is required on the receiving end.

Data Types

  1. Direct Text Messages: Simple text can be sent and received directly.

  2. Structured Data (JSON): Complex data structures can be sent as JSON, allowing for flexible data exchange. The receiving end must know how to handle and parse the JSON data.

  3. Geometry Data: Geometric data (like meshes, curves) can be serialized into JSON, encoded into bytes, compressed, and then sent. The receiving end must reverse this process to reconstruct the geometry.

Data Models

Portal provides JSON data models for various geometric entities. These models define the structure for serializing and deserializing geometric data:

Geometry Data Models

Packet Data Model

Packet is a generic model that wraps the data being sent. It includes the data itself and metadata about the data.

Headers

Portal uses headers to identify properties of the data being sent. These headers are used to determine the type of data being sent, the compression status, and other relevant information.

Field type Size (bytes) Description
MagicNumber byte[] 2 Header identifier. Value: 0x70, 0x6b (ASCII: pk)
isCompressed bool 1 Compression flag
isEncrypted bool 1 Encryption flag
CRC16 int16 2 CRC-16 checksum
size int32 4 Payload size
Total 10 Total header size

🚀 Code Examples

📜 License

Portal is licensed under the Apache License 2.0. See the LICENSE for more details.

📞 Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.