{"id":31131857,"url":"https://github.com/basementstudio/cloudpoints","last_synced_at":"2025-09-18T04:41:24.351Z","repository":{"id":314459946,"uuid":"1047589929","full_name":"basementstudio/CloudPoints","owner":"basementstudio","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-12T14:28:01.000Z","size":7013,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-12T16:53:39.464Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cloud-points.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basementstudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-30T18:56:28.000Z","updated_at":"2025-09-12T14:28:05.000Z","dependencies_parsed_at":"2025-09-12T17:10:38.019Z","dependency_job_id":null,"html_url":"https://github.com/basementstudio/CloudPoints","commit_stats":null,"previous_names":["basementstudio/cloudpoints"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/basementstudio/CloudPoints","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2FCloudPoints","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2FCloudPoints/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2FCloudPoints/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2FCloudPoints/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basementstudio","download_url":"https://codeload.github.com/basementstudio/CloudPoints/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2FCloudPoints/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275711274,"owners_count":25514200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-18T04:41:22.628Z","updated_at":"2025-09-18T04:41:24.341Z","avatar_url":"https://github.com/basementstudio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CloudPoints - Particle Visualization\n\nAn interactive web application for visualizing particles in 3D using TypeScript, React, and React Three Fiber.\n\n## Features\n\n### Two Visualization Modes\n\n**Option 1: Direct JSON Visualization**\n- Direct particle data loading from JSON files\n- Real-time rendering of positions and colors\n\n**Option 2: Texture-based Visualization**\n- Generates textures that store particle data\n- Positions encoded in RGB channels of a texture\n- Colors stored in a separate texture\n- Optimized for large particle quantities\n\n### Interactive Controls (Custom CSS UI)\n\n**Available Dot Shapes**\n- Circular dots\n- Square dots\n\n## Project Structure\n\n```\nsrc/\n├── components/\n│   ├── ParticleSystem.tsx          # Direct visualization (JSON/Houdini)\n│   ├── TextureParticleSystem.tsx   # Internal texture-based visualization\n│   └── DebugParticleSystem.tsx     # Debug system for troubleshooting\n├── hooks/\n│   └── useParticleData.ts          # Hook for complete data management\n├── types/\n│   └── particle.ts                 # TypeScript types (includes Houdini)\n├── utils/\n│   ├── houdiniParser.ts            # Parser and optimizer for Houdini format\n│   ├── textureGenerator.ts         # Internal and procedural texture generator\n│   ├── textureExporter.ts          # Basic PNG texture exporter\n│   ├── exrExporter.ts              # EXR-like Float32 exporter (HIGH PRECISION)\n│   └── textureLoader.ts            # Texture importer for verification\n├── App.tsx                         # Main component with custom CSS UI\n└── main.tsx                        # Entry point\n\npublic/\n├── point_data.json                 # Real Houdini data (1.2M particles)\n└── particles-example.json         # Internal example file\n```\n\n## Installation and Usage\n\n### Prerequisites\n- Node.js 16 or higher\n- npm or yarn\n\n### Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Run in development mode\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\n### Usage\n\n1. **Open the application**: The application will run at `http://localhost:5173`\n\n2. **Load Data**:\n   - **\"Load Houdini Data\"**: Load your Houdini `point_data.json` file (1.2M → optimized to 50K)\n   - **\"Load Custom JSON\"**: Load any JSON file with particle data\n   - **\"Test Simple Data\"**: 5 test particles for quick debugging\n\n### Workflow: Texture Export and Import\n\n#### Export (Particles → Textures)\n1. **Load data**: Use \"Load Houdini Data\" or \"Load Custom JSON\"\n2. **Select format**: Choose PNG, JPG, or EXR from dropdown\n3. **Export textures**: Click \"Export Textures\"\n4. **Automatic downloads**: 3 files are downloaded:\n   - `filename_positions_[FORMAT].png/jpg` - Normalized positions\n   - `filename_colors.png/jpg` - RGB colors\n   - `filename_metadata_[FORMAT].json` - Metadata with precision information\n\n##### Available Formats:\n- **PNG**: 8-bit RGBA, maximum compatibility\n- **JPG**: 8-bit RGB compressed, smaller files\n- **EXR**: Half Float (16-bit) if available, maximum precision\n\n#### Import (Textures → Verification)\n1. **Load textures**: Click \"Load from Textures\"\n2. **IMPORTANT**: Select ALL 3 FILES:\n   - `filename_positions_FORMAT.png` (positions)\n   - `filename_colors.png` (colors)\n   - `filename_metadata_FORMAT.json` (CRITICAL - without this = incorrect scaling)\n3. **Automatic verification**: App reconstructs particles from textures\n4. **Corrected coordinates**: No scaling issues (Y-axis inversion fixed)\n5. **Comparison**: Visually verify they match original data\n\n\u003e **WARNING**: If you don't select the **metadata JSON** file, you'll see incorrect bounds `[-20,-20,-20] to [20,20,20]` and the shape will appear compressed/incorrect.\n\n#### EXR Texture Structure\n\n##### Position Texture with Anti-Grid\n- **Format**: PNG with deterministic random mapping\n- **Precision**: 8-bit RGB with normalized coordinates 0-1\n- **Anti-Grid Mapping**:\n  - **Problem solved**: Exported textures maintained artificial grid pattern\n  - **Solution**: Deterministic shuffle mapping that preserves original organic distribution\n  - **Result**: Particles loaded from textures maintain natural Houdini appearance\n\n##### Color Texture (Standard PNG)\n- **Format**: Standard PNG with RGB channels\n- **Precision**: 8 bits per channel (sufficient for 0-1 colors)\n\n##### Dimensions and Performance\n- **Dimensions**: Power-of-2 square (e.g., 512x512 for ~250K particles)\n- **Position file**: 3x larger but infinitely more precise\n- **Compatibility**: All browsers (no native EXR support required)\n\n3. **Controls**:\n   - **Visualization Mode**: Switch between 'json' and 'texture'\n   - **Particle Size**: Adjust size (0.01 - 2.0, default 0.15)\n   - **Use Dots**: Toggle between dots and spheres\n   - **Bloom**: Control glow effects\n   - **Background Color**: Color picker and hex input for background\n   - **Invert Y-Axis**: Flip particles vertically\n\n4. **3D Navigation**:\n   - **Click and drag**: Rotate camera\n   - **Mouse wheel**: Zoom\n   - **Right click and drag**: Pan\n   - **RGB Gizmo**: X=Red, Y=Green, Z=Blue for orientation\n\n## Supported Data Formats\n\n### Houdini Format (Recommended)\n\nThe application natively supports JSON format exported by Houdini:\n\n```json\n[\n    {\n        \"P\": [2.049, -2.642, 0.584],\n        \"Cd\": [0.020, 0.014, 0.012]\n    },\n    {\n        \"P\": [1.367, -1.331, 0.596],\n        \"Cd\": [0.083, 0.108, 0.125]\n    }\n]\n```\n\n- `P`: Particle position [x, y, z]\n- `Cd`: Particle color [r, g, b] (values 0-1)\n\n### Automatic Optimization\n- Large files (\u003e100K particles) are automatically optimized\n- Smart subsampling to maintain performance\n- Visual indicator when optimization is applied\n\n### Internal Format (Alternative)\n\n```json\n{\n  \"metadata\": {\n    \"count\": 1000,\n    \"bounds\": {\n      \"min\": [-10, -10, -10],\n      \"max\": [10, 10, 10]\n    },\n    \"created\": \"2024-01-01T00:00:00Z\"\n  },\n  \"particles\": [\n    {\n      \"id\": \"particle_0\",\n      \"position\": [0, 0, 0],\n      \"color\": [1, 0.5, 0.2],\n      \"size\": 1.0\n    }\n  ]\n}\n```\n\n### Required Fields per Particle\n- `id`: Unique identifier (string)\n- `position`: Array of 3 numbers [x, y, z]\n- `color`: Array of 3 numbers [r, g, b] (values 0-1)\n- `size`: Optional number (size multiplier)\n\n## Technologies Used\n\n- **React 18**: UI Framework\n- **TypeScript**: Static typing\n- **React Three Fiber**: React renderer for Three.js\n- **@react-three/drei**: Utilities for R3F\n- **@react-three/postprocessing**: Post-processing effects\n- **Custom CSS**: Modern UI without external control dependencies\n- **Three.js**: 3D Engine\n- **Vite**: Build tool and dev server\n\n## Troubleshooting\n\n### \"Export Textures\" Button Disabled\n\n**Cause**: No particles loaded or loading in progress\n\n**Solution**: Load particle data first using one of the loading options\n\n### Texture Import Issues\n\n**Solution**: In \"Load from Textures\", select ALL 3 FILES:\n- `filename_positions_FORMAT.png`\n- `filename_colors.png`\n- **`filename_metadata_FORMAT.json`** ← **CRITICAL**\n\n## Performance\n\n### Optimizations for Houdini Files\n- **Automatic Detection**: Recognizes Houdini vs internal format automatically\n- **Streaming**: Efficient handling of large files (\u003e10MB)\n- **Smart Subsampling**: Automatically reduces particles to maintain 60 FPS\n- **Visual Indicators**: Shows when optimizations are applied\n\n### Rendering Modes\n- **JSON Option**: Optimal for up to ~50,000 particles (optimized)\n- **Texture Option**: Optimal for 50,000+ particles\n- **Dots vs Spheres**: Dots are more efficient for large quantities\n- **Bloom Effect**: May impact performance with many particles\n\n### Recommendations\n- For large Houdini files: Use 'texture' mode + 'dots' + automatic optimization\n- Datasets \u003c10K: Any configuration works well\n- Datasets \u003e100K: Automatic subsampling will be applied\n\n## Customization\n\n### Adding New Effects\nModify `src/App.tsx` and add more effects to the `EffectComposer`.\n\n### Changing Shaders\nShaders are defined in `ParticleSystem.tsx` and `TextureParticleSystem.tsx`.\n\n### New Controls\nAdd controls in the `CustomUI` component and the `UIState` state in `App.tsx`.\n\n## Build and Deploy\n\n### Local Build\n```bash\nnpm run build\n```\n\n### Deploy to Vercel\n1. Connect your GitHub repository to Vercel\n2. Vercel will automatically detect the Vite configuration\n3. Deploy with default settings\n\nThe application is optimized for production deployment and includes:\n- Automatic code splitting\n- Asset optimization\n- TypeScript compilation\n- Modern browser support","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasementstudio%2Fcloudpoints","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasementstudio%2Fcloudpoints","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasementstudio%2Fcloudpoints/lists"}