{"id":50933924,"url":"https://github.com/benab04/astro3d-core","last_synced_at":"2026-06-17T07:02:55.248Z","repository":{"id":290937315,"uuid":"976078510","full_name":"benab04/astro3d-core","owner":"benab04","description":"astro3d-core is a lightweight version of astro3d that lets you create custom visualizations of celestial bodies using your own maps. With no bundled textures or objects, it’s faster and smaller. Supports multiple overlays beyond normal and color maps for detailed, layered surface rendering.","archived":false,"fork":false,"pushed_at":"2025-05-01T13:35:21.000Z","size":80,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-09-17T22:40:18.774Z","etag":null,"topics":["3d-modelling","3d-models","celestial-bodies","planets","solar-system","space","threejs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/astro3d-core","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benab04.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-05-01T13:02:08.000Z","updated_at":"2025-05-01T14:10:09.000Z","dependencies_parsed_at":"2025-05-01T13:21:45.082Z","dependency_job_id":"0c17dc76-6bb4-49df-80ae-dafff1021296","html_url":"https://github.com/benab04/astro3d-core","commit_stats":null,"previous_names":["benab04/astro3d-core"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/benab04/astro3d-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benab04%2Fastro3d-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benab04%2Fastro3d-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benab04%2Fastro3d-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benab04%2Fastro3d-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benab04","download_url":"https://codeload.github.com/benab04/astro3d-core/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benab04%2Fastro3d-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34437451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"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":["3d-modelling","3d-models","celestial-bodies","planets","solar-system","space","threejs"],"created_at":"2026-06-17T07:02:52.094Z","updated_at":"2026-06-17T07:02:55.241Z","avatar_url":"https://github.com/benab04.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌍 astro3d-core\n\n**Create realistic 3D spheres of celestial bodies — the minimalist way.**\n\nThis lightweight package lets you easily generate customizable 3D mesh spheres with high-quality textures for use in any `three.js` scene. Whether you're building a planetarium, educational visualization, or just want a cool spinning planet on your homepage — astro3d-core provides the essential building blocks without unnecessary complexity.\n\n---\n\n## 🚀 Features\n\n- Minimalist API for textured 3D celestial bodies\n- Fully customizable geometry and material parameters\n- Support for overlay layers (clouds, atmospheres, etc.)\n- Multiple overlay support with customizable opacity and scale\n- Designed for use with **Three.js**\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install astro3d-core\n# or\nyarn add astro3d-core\n```\n\n---\n\n## 🔧 Usage\n\n### Creating a Basic Celestial Body\n\n```js\nimport * as THREE from \"three\";\nimport { createCelestialBody } from \"astro3d-core\";\nimport colorMapURL from \"path/to/earth-texture.jpg\";\nimport normalMapURL from \"path/to/earth-texture.jpg\";\n\nconst scene = new THREE.Scene();\nconst camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);\nconst renderer = new THREE.WebGLRenderer();\n\nrenderer.setSize(window.innerWidth, window.innerHeight);\ndocument.body.appendChild(renderer.domElement);\n\nconst earth = createCelestialBody({\n  radius: 3,\n  colorMapURL: colorMapURL,\n  normalMapURL: normalMapURL,\n  roughness: 0.4,\n  metalness: 0.001,\n});\n\nscene.add(earth);\ncamera.position.z = 10;\n\nfunction animate() {\n  requestAnimationFrame(animate);\n  earth.rotation.y += 0.005;\n  renderer.render(scene, camera);\n}\n\nanimate();\n```\n\n### Creating a Planet with Clouds\n\n```js\nimport * as THREE from \"three\";\nimport { createCelestialBody } from \"astro3d-core\";\nimport colorMapURL from \"path/to/earth-texture.jpg\";\nimport normalMapURL from \"path/to/earth-texture.jpg\";\nimport overlayMapURL from \"path/to/clouds-texture.png\";\n// Standard Three.js setup\n// ...\n\n// Create Earth with cloud layer\nconst earth = createCelestialBody({\n  radius: 3,\n  colorMapURL: colorMapURL,\n  normalMapURL: normalMapURL,\n  overlayMapURL: overlayMapURL,\n  overlayRadiusScale: 1.01, // Slightly larger than the planet\n  overlayOpacity: 0.6,\n  roughness: 0.4,\n  metalness: 0.001,\n  reflectivity: 0.1,\n});\n\nscene.add(earth);\n\n// Animation loop\nfunction animate() {\n  requestAnimationFrame(animate);\n  earth.rotation.y += 0.001;\n  // Cloud layer rotates with the planet as it's part of the same group\n  renderer.render(scene, camera);\n}\n\nanimate();\n```\n\n### Creating a Planet with Multiple Layers\n\n```js\nimport * as THREE from \"three\";\nimport { createCelestialBody } from \"astro3d-core\";\nimport colorMapURL from \"path/to/jupiter-texture.jpg\";\nimport overlay1 from \"path/to/jupiter-clouds-1.png\";\nimport overlay2 from \"path/to/jupiter-clouds-2.png\";\nimport overlay3 from \"path/to/jupiter-atmosphere.png\";\n// Create Jupiter with multiple cloud layers\nconst jupiter = createCelestialBody({\n  radius: 5,\n  colorMapURL: colorMapURL,\n  overlayMapURL: [overlay1, overlay2, overlay3],\n  overlayRadiusScale: [1.001, 1.005, 1.01], // Different scales for each layer\n  overlayOpacity: [0.4, 0.3, 0.2], // Different opacities\n  roughness: 0.6,\n  metalness: 0.0,\n});\n\nscene.add(jupiter);\n\n// Animation\nfunction animate() {\n  requestAnimationFrame(animate);\n  jupiter.rotation.y += 0.002;\n  renderer.render(scene, camera);\n}\n\nanimate();\n```\n\n---\n\n## 🛠️ Parameters\n\n### Celestial Body Parameters\n\nHere's the full list of options you can pass to `createCelestialBody`:\n\n| Parameter            | Type            | Default                     | Description                             |\n| -------------------- | --------------- | --------------------------- | --------------------------------------- |\n| `radius`             | `number`        | `3`                         | Radius of the sphere                    |\n| `widthSegments`      | `number`        | `64`                        | Number of horizontal segments           |\n| `heightSegments`     | `number`        | `64`                        | Number of vertical segments             |\n| `colorMapURL`        | `string`        | -                           | Path to the diffuse texture (color)     |\n| `normalMapURL`       | `string`        | -                           | Path to the normal map                  |\n| `overlayMapURL`      | `string\\|Array` | -                           | Path(s) to overlay texture(s)           |\n| `overlayRadiusScale` | `number\\|Array` | `1.001`                     | Scale factor(s) for overlay(s)          |\n| `overlayOpacity`     | `number\\|Array` | `0.6`                       | Opacity value(s) for overlay(s)         |\n| `oblateness`         | `number`        | `0`                         | Flattening of the sphere (0-1)          |\n| `roughness`          | `number`        | `0.8`                       | How rough the surface appears           |\n| `metalness`          | `number`        | `0.0`                       | How metallic the surface appears        |\n| `reflectivity`       | `number`        | `0.0`                       | Reflectiveness of the material          |\n| `clearcoat`          | `number`        | `0.0`                       | Clearcoat layer for extra gloss         |\n| `aoMapIntensity`     | `number`        | `0.8`                       | Intensity of ambient occlusion          |\n| `lightMapIntensity`  | `number`        | `1.0`                       | Intensity of baked lighting             |\n| `envMapIntensity`    | `number`        | `0.05`                      | Strength of environment reflection      |\n| `bumpScale`          | `number`        | `0.2`                       | Scale of bump mapping                   |\n| `normalScale`        | `number`        | `1.2`                       | Intensity of normal mapping             |\n| `flatShading`        | `boolean`       | `false`                     | Enable flat shading                     |\n| `transparent`        | `boolean`       | `false`                     | Enable transparency                     |\n| `side`               | `THREE.Side`    | `THREE.FrontSide`           | Which side(s) of the material to render |\n| `color`              | `THREE.Color`   | `new THREE.Color(0xFFFFFF)` | Base material color                     |\n| `initialRotation`    | `number`        | `-Math.PI / 2`              | Initial Y rotation of the sphere        |\n\n---\n\n## 🔍 Advanced Features\n\n### Multiple Overlay Support\n\nThe `overlayMapURL` parameter can accept either a string or an array of strings to create multiple overlays:\n\n```js\nconst planet = createCelestialBody({\n  // Basic parameters...\n  overlayMapURL: [\"path/to/layer1.png\", \"path/to/layer2.png\", \"path/to/layer3.png\"],\n  overlayRadiusScale: [1.001, 1.005, 1.01], // Different radius for each layer\n  overlayOpacity: [0.7, 0.5, 0.3], // Different opacity for each layer\n});\n```\n\n### Oblate Spheroid Support\n\nFor more realistic gas giants or rapidly rotating planets:\n\n```js\nconst jupiter = createCelestialBody({\n  // Basic parameters...\n  oblateness: 0.06478, // Jupiter's actual oblateness\n});\n```\n\n---\n\n## 🖼️ Textures\n\nThis package does not include textures. You'll need to provide URLs to your own texture maps.\n\nGood sources for planetary textures include:\n\n- [NASA Visible Earth](https://visibleearth.nasa.gov/)\n- [Solar System Scope](https://www.solarsystemscope.com/textures/)\n- [Planetary Pixel Emporium](http://planetpixelemporium.com/planets.html)\n\n---\n\n## 🚀 Example\n\n### Earth with Clouds and Atmospheric Glow\n\n```js\nimport * as THREE from \"three\";\nimport { createCelestialBody } from \"astro3d-core\";\nimport colorMapURL from \"path/to/earth-texture.jpg\";\nimport normalMapURL from \"path/to/earth-normal-map.jpg\";\nimport overlayMapURL1 from \"path/to/clouds.png\";\nimport overlayMapURL2 from \"path/to/atmosphere-glow.png\";\n\n// Standard Three.js setup\nconst scene = new THREE.Scene();\nconst camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);\nconst renderer = new THREE.WebGLRenderer({ antialias: true });\nrenderer.setSize(window.innerWidth, window.innerHeight);\ndocument.body.appendChild(renderer.domElement);\n\n// Add lights\nconst ambientLight = new THREE.AmbientLight(0x404040);\nconst directionalLight = new THREE.DirectionalLight(0xffffff, 2);\ndirectionalLight.position.set(5, 3, 5);\nscene.add(ambientLight);\nscene.add(directionalLight);\n\n// Create Earth with clouds and atmosphere\nconst earth = createCelestialBody({\n  radius: 3,\n  widthSegments: 64,\n  heightSegments: 64,\n  colorMapURL: colorMapURL,\n  normalMapURL : normalMapURL,\n  overlayMapURL : [overlayMapURL1, overlayMapURL2]\n  overlayRadiusScale: [1.01, 1.03],\n  overlayOpacity: [0.6, 0.2],\n  roughness: 0.4,\n  metalness: 0.001,\n  reflectivity: 0.1,\n  oblateness: 0.0034, // Earth's actual oblateness\n});\n\nscene.add(earth);\n\n// Set camera position\ncamera.position.z = 10;\n\n// Animation loop\nfunction animate() {\n  requestAnimationFrame(animate);\n  earth.rotation.y += 0.001;\n  renderer.render(scene, camera);\n}\n\nanimate();\n```\n\n---\n\n## 💫 Final Thoughts\n\nastro3d-core is a lightweight library focused on providing the essential building blocks for creating realistic celestial bodies in your Three.js scenes. By keeping the API minimal, we give you the flexibility to build exactly what you need without the overhead.\n\nIf you find this package helpful, consider giving it a star 🌟 or contributing with a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenab04%2Fastro3d-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenab04%2Fastro3d-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenab04%2Fastro3d-core/lists"}