ply_viewer 0.0.3

A highly customizable 3D PLY point cloud & mesh viewer widget for Flutter, supporting local files, assets, raw bytes, and network URLs using WebGL and Three.js.

ply_viewer

A highly customizable, high-performance 3D PLY point cloud & mesh viewer widget for Flutter. Powered by WebGL and Three.js, supporting multi-source rendering (Network URLs, Local Files, Assets, and Memory Bytes).

---

🌟 Key Features

• 📦 Multi-Format & Multi-Source Support:
  • Render multiple 3D formats: PLY, glTF, GLB, FBX, USDZ, OBJ, STL.
  • Network HTTP/HTTPS URLs (PlySource.network) with Auto-Conversion for GitHub Blob URLs.
  • Device Local Storage files (PlySource.file)
  • Flutter Application Assets (PlySource.asset)
  • Memory Raw Byte Arrays (PlySource.bytes)
• 🎨 High Customizability: Configure background colors, point sizes, default vertex colors, FOV, grid helpers, and accent colors.
• 🎛️ Rich UI Overlay Controls:
  • Glassmorphic top toolbar with zoom, point size adjustment, reset view, and density selectors.
  • Interactive 3D D-Pad navigation for strafing & forward/backward movement.
  • Height elevation up/down controls.
  • 3-Way Camera Gesture Modes: Orbit (Rotate object), Pan (Translate), and Look (First-Person View).
• ⚙️ Programmatic Controller: Control camera, zoom, view mode, point size, and point density dynamically via PlyViewerController.
• ⚡ Downsampling & Performance: Built-in point density sampling options (80K, 200K, 500K, Ultra) for smooth performance on mobile devices.

---

📦 Installation

Add ply_viewer to your pubspec.yaml:

dependencies:
  ply_viewer: ^0.0.1

Run flutter pub get in your terminal.

---

🚀 Quick Start

1. Load PLY from Network URL

import 'package:flutter/material.dart';
import 'package:ply_viewer/ply_viewer.dart';

class NetworkPlyScreen extends StatelessWidget {
  const NetworkPlyScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('3D Network PLY Viewer')),
      body: PlyViewer(
        source: PlySource.network('https://example.com/models/room_scan.ply'),
        config: const PlyViewerConfig(
          accentColor: Colors.orange,
          showGrid: true,
          showToolbar: true,
        ),
      ),
    );
  }
}

2. Load PLY from Local File

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:ply_viewer/ply_viewer.dart';

class LocalFilePlyScreen extends StatelessWidget {
  final File plyFile;
  const LocalFilePlyScreen({super.key, required this.plyFile});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Local File PLY')),
      body: PlyViewer(
        source: PlySource.file(plyFile),
        config: const PlyViewerConfig(
          backgroundColor: Color(0xFF111111),
          initialPointSize: 0.03,
        ),
      ),
    );
  }
}

3. Load PLY from Asset or Bytes

// Load from Asset
PlyViewer(
  source: PlySource.asset('assets/models/sample_room.ply'),
)

// Load from Bytes
PlyViewer(
  source: PlySource.bytes(uint8ListBytes),
)

---

🎛️ Programmatic Control with PlyViewerController

class ControlledPlyViewer extends StatefulWidget {
  const ControlledPlyViewer({super.key});

  @override
  State<ControlledPlyViewer> createState() => _ControlledPlyViewerState();
}

class _ControlledPlyViewerState extends State<ControlledPlyViewer> {
  final PlyViewerController _controller = PlyViewerController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          PlyViewer(
            source: PlySource.network('https://example.com/room.ply'),
            controller: _controller,
          ),
          Positioned(
            bottom: 20,
            right: 20,
            child: FloatingActionButton(
              onPressed: () => _controller.resetView(),
              child: const Icon(Icons.refresh),
            ),
          ),
        ],
      ),
    );
  }
}

Available Controller Methods:

Method	Description
resetView()	Resets camera target, position, and zoom back to default bounds.
setPointDensity(PlyPointDensity density)	Dynamically changes point sampling count (low, medium, high, ultra).
setPointSize(double size)	Sets the point size rendering value.
toggleGrid(bool visible)	Shows or hides the ground plane grid.
setViewMode(PlyViewMode mode)	Switches between PlyViewMode.outside and PlyViewMode.inside.
zoom(double step)	Zooms camera in (1.0) or out (-1.0).
move(PlyDirection direction)	Moves camera in specified direction (forward, backward, left, right, up, down).

---

🛠️ Configuration Parameters (PlyViewerConfig)

PlyViewerConfig(
  backgroundColor: Color(0xFF1A1A1A), // Viewport background color
  initialPointSize: 0.02,            // Initial point cloud point size
  defaultPointColor: Color(0xFFFF8C00),// Default color for uncolored points
  initialDensity: PlyPointDensity.medium,// Default density (Low, Medium, High, Ultra)
  showToolbar: true,                 // Show/hide glassmorphic toolbar
  showDPad: true,                    // Show/hide movement D-Pad
  showElevationControls: true,       // Show/hide height controls
  showViewToggle: true,              // Show/hide Inside/Outside view mode button
  showGrid: true,                    // Show/hide floor grid
  accentColor: Colors.orange,        // Primary accent theme color
  fov: 60.0,                         // Camera Field of View
)

---

📄 License

MIT License - see LICENSE for details.