{"_id":"@alekstar79/3d-polyhedra","name":"@alekstar79/3d-polyhedra","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alekstar79/3d-polyhedra","description":"Interactive 3D polyhedra renderer (TypeScript)","author":{"name":"Aleksey Tarasenko","email":"alekstar79@yandex.ru"},"version":"1.0.0","type":"module","license":"MIT","private":false,"keywords":["3d","typescript","polyhedra","renderer"],"main":"lib-dist/polyhedra3d.umd.js","module":"lib-dist/polyhedra3d.es.js","types":"lib-dist/index.d.ts","homepage":"https://alekstar79.github.io/3d-polyhedra","repository":{"type":"git","url":"git+https://github.com/alekstar79/3d-polyhedra.git"},"bugs":{"url":"https://github.com/alekstar79/3d-polyhedra/issues"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"scripts":{"dev":"vite","build:demo":"vite build","build:gh-pages":"GH_PAGES=true npm run build:demo","build:lib":"vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly","build":"npm run build:lib && npm run build:demo","preview":"vite preview","prepublishOnly":"npm run build:lib"},"devDependencies":{"@types/node":"^26.4.1","vite":"^8.2.2"},"_id":"@alekstar79/3d-polyhedra@1.0.0","gitHead":"a55d2e15f402445dd08b6a1544d6a1cddf13f21a","_nodeVersion":"22.21.1","_npmVersion":"10.9.9","dist":{"integrity":"sha512-WqXEi/aErMRRpOaojcXt7nwh3EVgXOr5/PB4NwhY+NKLkKVvrJTtPa1aM0A0crvjn1frKsRQHhq5e+A7lta9Og==","shasum":"f8488a1313d76649a757d02d04504177c310a056","tarball":"https://registry.npmjs.org/@alekstar79/3d-polyhedra/-/3d-polyhedra-1.0.0.tgz","fileCount":14,"unpackedSize":46302,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGZNer3PvA4UUYuO2vJRRHqpu0EHJoh6FJsmC1LGn9MIAiARJyNnb549G8jp+KBZ8ARBD0SwOsAtjNm0+1Sm1f43pA=="}]},"_npmUser":{"name":"alekstar79","email":"alekstar79@yandex.ru"},"directories":{},"maintainers":[{"name":"alekstar79","email":"alekstar79@yandex.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/3d-polyhedra_1.0.0_1788360380515_0.014247071707810921"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T14:46:20.286Z","1.0.0":"2026-09-02T14:46:20.655Z","modified":"2026-09-02T14:46:21.072Z"},"maintainers":[{"name":"alekstar79","email":"alekstar79@yandex.ru"}],"description":"Interactive 3D polyhedra renderer (TypeScript)","homepage":"https://alekstar79.github.io/3d-polyhedra","keywords":["3d","typescript","polyhedra","renderer"],"repository":{"type":"git","url":"git+https://github.com/alekstar79/3d-polyhedra.git"},"author":{"name":"Aleksey Tarasenko","email":"alekstar79@yandex.ru"},"bugs":{"url":"https://github.com/alekstar79/3d-polyhedra/issues"},"license":"MIT","readme":"# 3D Polyhedra Library\n\n[![npm version](https://badge.fury.io/js/3d-polyhedra.svg)](https://www.npmjs.com/package/3d-polyhedra)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)\n[![Vite](https://img.shields.io/badge/Vite-8.2-646CFF)](https://vitejs.dev/)\n\n**Interactive 3D polyhedra renderer with smooth subdivision, real-time lighting, and intuitive controls.**\n\n![3D-Polyhedrons](3D-Polyhedrons.png)\n\n[Live Demo](https://alekstar79.github.io/3d-polyhedra)\n\n<!-- TOC -->\n* [3D Polyhedra Library](#3d-polyhedra-library)\n  * [Features](#features)\n  * [Installation](#installation)\n    * [For library usage](#for-library-usage)\n    * [For development / demo](#for-development--demo)\n  * [Demo](#demo)\n  * [Usage Examples](#usage-examples)\n    * [Simple renderer setup](#simple-renderer-setup)\n    * [Dynamic updates](#dynamic-updates)\n    * [Low-level control](#low-level-control)\n  * [More Examples](#more-examples)\n  * [API Reference](#api-reference)\n    * [`Renderer`](#renderer)\n      * [Constructor](#constructor)\n      * [Methods](#methods)\n      * [Properties](#properties)\n    * [Types](#types)\n    * [Low-level Components](#low-level-components)\n  * [Project Structure](#project-structure)\n  * [Build & Development](#build--development)\n    * [Commands](#commands)\n    * [Library Build Output](#library-build-output)\n  * [Browser Support](#browser-support)\n  * [Contributing](#contributing)\n  * [License](#license)\n  * [Contact](#contact)\n<!-- TOC -->\n\n## Features\n\n- **5 Platonic Solids** – Tetrahedron, Cube, Octahedron, Dodecahedron, Icosahedron\n- **Dynamic Subdivision** – level 0–4 for smooth surfaces\n- **Interactive Controls** – mouse drag rotation, touch support\n- **Real-time Lighting** – dynamic directional light based on pointer position\n- **Hole Effect** – configurable aperture for wireframe-like style\n- **Color Palette** – hue shift and random per-face colors\n- **Performance** – optimized with FPS counter\n- **Framework Agnostic** – pure TypeScript, no external dependencies (only for development)\n\n---\n\n## Installation\n\n### For library usage\n\n```bash\nnpm install @alekstar79/3d-polyhedra\n```\n\n### For development / demo\n\nClone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/alekstar79/3d-polyhedra.git\ncd 3d-polyhedra\nnpm install\n```\n\n---\n\n## Demo\n\nRun the demo locally:\n\n```bash\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) to see the interactive 3D scene with control panel.\n\nTo build the demo for production:\n\n```bash\nnpm run build:demo\n```\n\nThe output will be in the `dist` folder.\n\n---\n\n## Usage Examples\n\nBelow are two primary ways to use the library – the high-level `Renderer` and low-level components for full control.\n\n### Simple renderer setup\n\nThe easiest way to get started is to use the `Renderer` class. It handles all the rendering, animation loop, and interaction.\n\n```typescript\nimport { Renderer } from '@alekstar79/3d-polyhedra';\n\nconst canvas = document.getElementById('canvas') as HTMLCanvasElement;\n\nconst renderer = new Renderer({\n  canvas,\n  polyhedronType: 3,   // Dodecahedron\n  division: 1,\n  hole: 0.3,\n  color: 0.6,\n  speed: 1.5,\n});\n\nrenderer.start();\n```\n\n### Dynamic updates\n\nYou can change any parameter on the fly after initialization.\n\n```typescript\n// ... after renderer is started\n\n// Switch to Icosahedron with higher subdivision and different color\nrenderer.update({\n  polyhedronType: 4,\n  division: 2,\n  color: 0.9,\n});\n\n// You can also add rotation from external controls (e.g., keyboard)\nrenderer.addRotation(0.1, 0.05);\n\n// Get current state\nconst state = renderer.getState();\nconsole.log(state);\n```\n\n### Low-level control\n\nFor advanced scenarios where you need to customize every step, use the individual components directly.\n\n```typescript\nimport {\n  Icosahedron,\n  Projector,\n  RotationController,\n  LightingCalculator,\n  PolyhedronDrawer,\n} from '@alekstar79/3d-polyhedra';\n\nconst canvas = document.getElementById('canvas') as HTMLCanvasElement;\nconst ctx = canvas.getContext('2d')!;\n\n// Set up components\nconst poly = new Icosahedron();\nconst projector = new Projector([0, 0, 5], 0.5, canvas.width, canvas.height);\nconst rotation = new RotationController();\nconst lighting = new LightingCalculator();\nlighting.setLightDirection([1, 1, 1]);\nconst drawer = new PolyhedronDrawer(ctx);\n\nfunction animate() {\n  const matrix = rotation.update(16, 1.0);\n  const level = 0;\n\n  const verts = poly.verticesD[level];\n  const faces = poly.facesD[level];\n  const normals = poly.faceNormalsD[level];\n  const centers = poly.faceCentersD[level];\n  const colors = poly.colorsD[level];\n\n  // Apply rotation, project, calculate lighting, and draw\n  const rotatedVerts = verts.map(v => applyMatrix(v, matrix));\n  const rotatedNormals = normals.map(n => applyMatrix(n, matrix));\n  const rotatedCenters = centers.map(c => applyMatrix(c, matrix));\n\n  const projectedVerts = projector.projectMany(rotatedVerts);\n  const projectedCenters = projector.projectMany(rotatedCenters);\n  const intensities = lighting.calculateIntensities(rotatedNormals);\n\n  ctx.clearRect(0, 0, canvas.width, canvas.height);\n  drawer.draw(\n    projectedVerts,\n    faces,\n    projectedCenters,\n    colors,\n    0.0,          // hole size\n    intensities,\n    0.5           // color parameter\n  );\n\n  requestAnimationFrame(animate);\n}\nanimate();\n\n// Helper: apply 3x3 matrix to a vector\nfunction applyMatrix(v: [number, number, number], m: readonly number[]): [number, number, number] {\n  const [x, y, z] = v;\n  const [m00, m01, m02, m10, m11, m12, m20, m21, m22] = m;\n  return [\n    m00 * x + m01 * y + m02 * z,\n    m10 * x + m11 * y + m12 * z,\n    m20 * x + m21 * y + m22 * z,\n  ];\n}\n```\n\n---\n\n## More Examples\n\nThe repository includes a dedicated `examples/` folder with ready-to-run TypeScript files that demonstrate real-world use cases:\n\n- **basic-dodecahedron.ts** – minimal setup with a Dodecahedron.\n- **subdivision-demo.ts** – shows dynamic subdivision and switching between polyhedra.\n- **low-level.ts** – full low-level implementation (same as above but complete).\n\nYou can browse or download these files directly from the [examples/](https://github.com/alekstar79/3d-polyhedra/tree/main/examples) folder.\n\n---\n\n## API Reference\n\n### `Renderer`\n\nMain class that orchestrates the rendering pipeline.\n\n#### Constructor\n\n```typescript\nnew Renderer(config: RendererConfig)\n```\n\n| Parameter               | Type                | Description                                                        |\n|-------------------------|---------------------|--------------------------------------------------------------------|\n| `config.canvas`         | `HTMLCanvasElement` | Canvas element to render on                                        |\n| `config.polyhedronType` | `PolyhedronType`    | 0=Tetrahedron, 1=Cube, 2=Octahedron, 3=Dodecahedron, 4=Icosahedron |\n| `config.division`       | `number`            | Subdivision level (0–4)                                            |\n| `config.hole`           | `number`            | Hole size (0–0.9)                                                  |\n| `config.color`          | `number`            | Color hue parameter (0–1.2)                                        |\n| `config.speed`          | `number`            | Rotation speed multiplier                                          |\n\n#### Methods\n\n| Method                               | Description                                                   |\n|--------------------------------------|---------------------------------------------------------------|\n| `update(config: RendererUpdate)`     | Update one or more parameters (partial update)                |\n| `getState(): RendererState`          | Returns current full state                                    |\n| `start(): void`                      | Starts the animation loop                                     |\n| `stop(): void`                       | Stops animation (currently placeholder)                       |\n| `resize(): void`                     | Manually trigger resize (handles window resize automatically) |\n| `addRotation(deltaX, deltaY): void`  | Add relative rotation (for custom controls)                   |\n| `setLightDirection(dir: Vec3): void` | Set light direction vector                                    |\n\n#### Properties\n\n| Property      | Type                    | Description              |\n|---------------|-------------------------|--------------------------|\n| `onFpsUpdate` | `(fps: number) => void` | Callback for FPS updates |\n\n### Types\n\n```typescript\ntype PolyhedronType = 0 | 1 | 2 | 3 | 4;\n\ninterface RendererConfig {\n  canvas: HTMLCanvasElement;\n  polyhedronType: PolyhedronType;\n  division: number;\n  hole: number;\n  color: number;\n  speed: number;\n}\n\ninterface RendererState extends RendererConfig {}\n\ntype RendererUpdate = Partial<RendererState>;\n\ntype Vec3 = readonly [x: number, y: number, z: number];\ntype Vec2 = readonly [x: number, y: number];\ntype Mat3 = readonly [ ... ]; // 9 numbers\n```\n\n### Low-level Components\n\nIf you need more control, you can use individual components:\n\n- `Polyhedron` – base class (extended by `Tetrahedron`, `Cube`, etc.)\n- `Projector` – 3D to 2D projection\n- `RotationController` – handles rotation accumulation\n- `LightingCalculator` – calculates face intensities\n- `PolyhedronDrawer` – renders faces on Canvas 2D\n\n---\n\n## Project Structure\n\n```\nsrc/\n├── lib/                     # Library source\n│   ├── index.ts            # Public API entry\n│   ├── types.ts            # Interfaces and types\n│   ├── math.ts             # Vector/matrix utilities\n│   ├── polyhedron.ts       # Polyhedron classes\n│   ├── projector.ts        # Projection logic\n│   ├── rotation-controller.ts\n│   ├── lighting-calculator.ts\n│   ├── polyhedron-drawer.ts\n│   └── renderer.ts         # Main renderer\n├── demo/                    # Demo application\n│   ├── app.ts\n│   ├── ui.ts\n│   ├── index.html\n│   └── styles.css\n├── examples/                # Example usage files\n│   ├── basic-dodecahedron.ts\n│   ├── subdivision-demo.ts\n│   └── low-level.ts\n├── dist/                    # Built demo (output)\n├── lib-dist/                # Built library (for npm)\n├── package.json\n├── tsconfig.json\n├── vite.config.ts          # Demo build config\n├── vite.lib.config.ts      # Library build config\n└── README.md\n```\n\n---\n\n## Build & Development\n\n### Commands\n\n| Command              | Description                                             |\n|----------------------|---------------------------------------------------------|\n| `npm run dev`        | Start demo dev server (port 3000)                       |\n| `npm run build:demo` | Build demo into `dist`                                  |\n| `npm run build:lib`  | Build library into `lib-dist` (JS + .d.ts)              |\n| `npm run build`      | Build both library and demo                             |\n| `npm run preview`    | Preview built demo                                      |\n| `npm publish`        | Publish library to npm (runs `build:lib` automatically) |\n\n### Library Build Output\n\n- `lib-dist/polyhedra3d.es.js` – ESM format\n- `lib-dist/polyhedra3d.umd.js` – UMD format (for browsers, AMD, CommonJS)\n- `lib-dist/index.d.ts` – TypeScript declarations\n\n---\n\n## Browser Support\n\nThe library works in all modern browsers that support:\n- Canvas 2D\n- ES6 modules\n- Touch events (for mobile)\n\nTested on:\n- Chrome 90+\n- Firefox 88+\n- Safari 14+\n- Edge 90+\n- Mobile Safari/Chrome\n\n---\n\n## Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nPlease ensure your code passes TypeScript strict checks and includes proper tests (if applicable).\n\n---\n\n## License\n\nThis project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Contact\n\n- **Author**: [alekstar79](https://github.com/alekstar79)\n- **Project Home**: [https://github.com/alekstar79/3d-polyhedra](https://github.com/alekstar79/3d-polyhedra)\n- **Issues**: [https://github.com/alekstar79/3d-polyhedra/issues](https://github.com/alekstar79/3d-polyhedra/issues)\n","readmeFilename":"README.md","_rev":"1-21c5f02e08d1a8c836dcae3424c0b8f6"}