🌈 three.pipeline-aide - Pipeline Rendering Magic Wand ✨

"Let pipelines grow like magic in the 3D world!" 🪄💫

📖 Project Introduction

Hello hello~ Welcome to the wonderful world of three.pipeline-aide! (◕‿◕✿)

This is a super dynamic pipeline rendering library based on Three.js, specifically designed to create smooth and fluid pipeline effects in 3D space! Whether you want to create a sci-fi energy transmission tube 🌟, a water pipe system in a game 🔧, or even flowing light lines in an art installation 🎨, this project can handle it all with ease!

✨ Core Features

• 🎯 Intelligent Corner Handling - Automatically identifies and smooths pipe bends, eliminating sharp right angles!
• 📏 Dynamic Progress Control - Let the pipeline grow slowly like a snake, super ceremonial! 🐍
• 🎨 UV Texture Scrolling - Make textures flow on the pipe surface, as if the pipeline has come to life! 💧
• 🔧 Real-time Parameter Adjustment - Radius, segments, corner radius... all parameters can be dynamically adjusted at runtime!
• 💪 Full TypeScript Support - Type safety for an enhanced development experience! No more typos in property names!
• 🚀 High-performance Rendering - Based on BufferGeometry underlying optimization, smooth operation without pressure!

🎮 What can you do with it?

🌊 Sci-fi energy pipelines          💧 Fluid transport pipeline visualization
🔮 Light trajectories in magic circles          🎵 Music visualization waveform pipelines
🎆 Particle effect path guidance          🏗️ Industrial pipeline digital twins

🚀 Quick Start

Install Dependencies

pnpm install  # or npm install / yarn install

Run Demo

# Start the development server and experience the magic! ✨
npm run dev
pnpm dev

Basic Usage

import * as THREE from 'three';
import { PipelinePointAide, Pipeline3Geometry } from './src/core';

// 1️⃣ Create path point aide
const pathPointList = new PipelinePointAide();
pathPointList.set([
    new THREE.Vector3(0, 0, 0),
    new THREE.Vector3(5, 3, 0),
    new THREE.Vector3(10, 0, 5)
], 0.3, 10); // corner radius 0.3, corner segments 10

// 2️⃣ Create pipeline geometry
const geometry = new Pipeline3Geometry({
    pathPointList: pathPointList,
    options: { 
        radius: 0.2,        // pipeline radius
        radialSegments: 8   // radial segments
    }
});

// 3️⃣ Create material and mesh
const material = new THREE.MeshPhysicalMaterial({
    color: 0x58DEDE,
    metalness: 0.8,
    roughness: 0.2
});

const tube = new THREE.Mesh(geometry, material);
scene.add(tube);

// 4️⃣ Want dynamic effects? Easy!
geometry.update(pathPointList, { progress: 0.5 }); // Pipeline grows to half length!

🎛️ API Documentation

PipelinePointAide - Path Point Aide

Core class for managing pipeline paths, responsible for converting discrete key points into smooth curved paths~

const pathPointList = new PipelinePointAide();

/**
 * Set path points
 * @param points - Key points array (Vector3[])
 * @param cornerRadius - Corner radius (default: 0.1)
 * @param cornerSplit - Corner segments (default: 10)
 * @param up - Forced up direction, null for auto-calculation (default: null)
 * @param close - Whether to close the path (default: false)
 */
pathPointList.set(points, cornerRadius, cornerSplit, up, close);

// Get total path length
const totalDistance = pathPointList.distance();

Pipeline3Geometry - Pipeline Geometry

Geometry class that generates 3D pipeline meshes based on path point lists!

// Initialization method 1: Using configuration object
const geometry = new Pipeline3Geometry({
    pathPointList: pathPointList,
    options: {
        radius: 0.2,          // pipeline radius
        radialSegments: 8,    // radial segments (more for smoother)
        startRad: 0,          // start angle
        progress: 1           // rendering progress (0-1)
    },
    usage: THREE.StaticDrawUsage
});

// Initialization method 2: Pre-allocate maximum vertices
const geometry = new Pipeline3Geometry(1000, false);

// Dynamically update geometry
geometry.update(pathPointList, {
    radius: 0.3,
    radialSegments: 12,
    progress: 0.8
});

Pipeline2Geometry - Path Geometry (Flat Ribbon)

Similar to Pipeline3Geometry, but generates flat ribbon geometry, suitable for roads, rivers, etc.~

const geometry = new Pipeline2Geometry({
    pathPointList: pathPointList,
    options: {
        width: 0.5,           // ribbon width
        progress: 1,          // rendering progress
        arrow: true,          // whether to show arrow
        side: 'both'          // 'left' | 'right' | 'both'
    }
});

🎨 Demo Instructions

The project includes a complete interactive Demo (demo/demo01.ts) that showcases all core features:

• 🎛️ GUI Control Panel - Real-time adjustment of all parameters
• 🎬 Progress Animation - Press P to play pipeline growth animation
• 🌊 UV Scrolling - Texture flowing effect on the pipeline surface
• 🎨 Color Adjustment - Real-time pipeline color changes
• 📐 Geometry Parameters - Adjust radius, segments, corner handling, etc.

🛠️ Tech Stack

• Three.js - 3D rendering engine
• TypeScript - Type-safe JavaScript superset
• lil-gui - Lightweight GUI control panel
• Vite - Fast frontend build tool

📁 Project Structure

three.pipeline-aide/
├── src/
│   ├── annotate/               # Documentation annotations
│   │   ├── Pipeline2Geometry.md
│   │   ├── Pipeline3Geometry.md
│   │   ├── PipelinePoint.md
│   │   └── PipelinePointAide.md
│   ├── core/                    # Core library code
│   │   ├── PipelinePoint.ts     # Path point class
│   │   ├── PipelinePointAide.ts # Path point aide class
│   │   ├── Pipeline2Geometry.ts # Path geometry (flat ribbon)
│   │   ├── Pipeline3Geometry.ts # Pipeline geometry (round tube)
│   │   └── index.ts             # Export entry
├── demo/                        # Demo code
│   └── demo01.ts                # Interactive demo
├── index.html                   # HTML entry
├── main.ts                      # TypeScript entry
└── package.json

🌟 Advanced Tips

💡 Performance Optimization Tips

// 1. Pre-allocate geometry size to avoid runtime reallocation
const geometry = new Pipeline3Geometry(10000); // Supports up to 10000 vertices

// 2. Use segments appropriately
// Don't blindly pursue high subdivision, adjust according to actual needs
const options = {
    radialSegments: 8,    // 8 segments are usually smooth enough
    cornerSplit: 10       // 10 segments at corners are smooth enough
};

// 3. Use requestAnimationFrame for progress animations
function animate() {
    requestAnimationFrame(animate);
    geometry.update(pathPointList, { progress: currentProgress });
    renderer.render(scene, camera);
}

🎯 Creating Closed Pipelines

const points = [
    new THREE.Vector3(0, 0, 0),
    new THREE.Vector3(5, 0, 0),
    new THREE.Vector3(5, 5, 0),
    new THREE.Vector3(0, 5, 0)
];

pathPointList.set(points, 0.3, 10, null, true); // Last parameter true = closed!

🌈 Custom Material Effects

// Glowing pipeline effect ✨
const material = new THREE.MeshPhysicalMaterial({
    color: 0x00ffff,
    emissive: 0x0088ff,      // self-illumination
    emissiveIntensity: 0.5,
    metalness: 0.9,
    roughness: 0.1,
    transparent: true,
    opacity: 0.9
});

// Translucent pipeline effect 💧
const material = new THREE.MeshPhysicalMaterial({
    color: 0x58DEDE,
    transparent: true,
    opacity: 0.6,
    side: THREE.DoubleSide,
    depthWrite: false
});

🐛 Common Issues

Q: Why is the pipeline not smooth?
A: Increase the radialSegments parameter! Default is 8, try 16 or higher~

Q: What to do if there are wrinkles at corners?
A: Adjust cornerRadius and cornerSplit, increasing these values will make corners smoother!

Q: How to make the pipeline grow slowly from one end?
A: Use the progress parameter! Gradually increase from 0 to 1, combine with animation loop and you're good to go!

Q: Texture display issues?
A: Ensure texture wrapS and wrapT are set to THREE.RepeatWrapping, and adjust repeat and offset as needed~

🤝 Contribution Guide

Welcome to submit Issues and Pull Requests! Whether it's bug reports, feature suggestions, or code contributions, we greatly appreciate it! (◕‿◕)

📝 Changelog

v1.0.0 (2024)

• ✨ Full TypeScript type support
• 🎯 Core pipeline rendering algorithm
• 🎨 Dynamic parameter adjustment
• 🌊 UV scrolling effect
• 🎬 Progress animation system

Acknowledgements

This project is a derivative work based on the outstanding research and code from the following projects:

• [three.path] by [shawn0326].
  We are deeply grateful to the original authors for their foundational work.
  Without their open-source release of the [specific algorithm] under the [MIT], this project would not exist.

Our work focuses on [your unique contribution], which includes:

• [TypeScript update]

For some original source codes, please visit: [https://github.com/shawn0326/three.path]

License

This project is licensed under the [MIT] – see the LICENSE file for details.

Note: This project is not affiliated with the original authors of [three.path].