react-three-map 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# react-three-map
+
+## 0.2.0
+
+### Minor Changes
+
+- b210a12: Support to render `react-three-map` on demand via `<Canvas frameloop="ondemand">`
+- 557920a: Add Mapbox support.
+
+  - If you use **Mapbox** `import { Canvas } from "react-three-map"`
+  - If you use **Maplibre** `import { Canvas } from "react-three-map/maplibre"`
+
+### Patch Changes
+
+- 83de85c: Fix camera matrix bug where it may have invalid state on start.

package/README.md

@@ -1,78 +1,135 @@
 # React Three Map
 
-⚠️ **Alpha Warning: This library is currently in its alpha phase. While functional, it's still under active development and may have bugs. Please use with caution in production and feel free to report any issues you encounter. Thank you for your understanding!**
-
+[![Version](https://img.shields.io/npm/v/react-three-map?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/@react-three/fiber)
 
-React Three Map seamlessly integrates three.js with MapLibre and Mapbox using React, allowing you to bring the power of 3D rendering to your maps in a declarative manner.
 
-This package offers a Three layer that allows you to use `@react-three/fiber` within `react-map-gl` and is compatible with both Mapbox and Maplibre.
+⚠️ **Alpha Warning: This library is currently in its alpha phase. While functional, it's still under active development and may have bugs. Please use with caution in production and feel free to report any issues you encounter. Thank you for your understanding!**
 
-## Examples
+`react-three-map` is a bridge to use [`react-three-fiber`](https://github.com/pmndrs/react-three-fiber) inside [`react-map-gl`](https://github.com/visgl/react-map-gl).
 
-Check out our [stories](https://rodrigohamuy.github.io/react-three-map) to see it in action.
+Until now you had:
 
-## Installation
+| imperative | declarative (react) |
+| --- | --- |
+| Mapbox GL JS | react-map-gl |
+| THREE.js | react-three-fiber |
 
-You can install React Three Map via npm:
+Now with `react-three-map`, you can use them together :fist_right::fist_left:.
 
-```bash
+```sh
 npm install react-three-map
 ```
 
+Find use examples in our [Stories :book:](https://rodrigohamuy.github.io/react-three-map).
+
+## What does it look like?
+
 
-## Getting Started
+<table>
+  <tbody>
+    <tr>
+      <td>Let's build the same <code>react-three-fiber</code> basic example, but now it can be inside a map. (<a href="https://codesandbox.io/p/sandbox/vigorous-snyder-2n9vpl?file=%2Fsrc%2FApp.tsx%3A48%2C45">live demo</a>).</td>
+      <td>
+        <a href="https://codesandbox.io/p/sandbox/vigorous-snyder-2n9vpl?file=%2Fsrc%2FApp.tsx%3A48%2C45">
+          <img src="docs/basic-app.gif" />
+        </a>
+      </td>
+    </tr>
+  </tbody>
+</table>
 
-Just add `<Canvas>` inside the map and start using R3F as usual. That easy!
+1. Import `Canvas` from `react-three-map` instead of `@react-three/fiber`.
+2. Give it a latitude and longitude so it knows where to position the scene in the map.
+3. Everything else should work just as usual.
 
 ```jsx
-import Map from 'react-map-gl/maplibre';
-import { Canvas } from 'react-three-map';
-
-...
-
-<Map initialViewState={{ latitude: 51, longitude: 0, zoom: 22 }}>
-  <Canvas latitude={51} longitude={0}>
-    {/* Use react-three-fiber as usual in here */}
-    <mesh>
-      <boxBufferGeometry attach="geometry" args={[1, 1, 1]} />
-      <meshStandardMaterial attach="material" color="orange" />
-    </mesh>
-  </Canvas>
-</Map>
-...
+import "maplibre-gl/dist/maplibre-gl.css"
+import { createRoot } from 'react-dom/client'
+import React, { useRef, useState } from 'react'
+import { useFrame } from "@react-three/fiber"
+import { useRef, useState } from "react"
+import Map from "react-map-gl/maplibre"
+import { Canvas } from "react-three-map/maplibre" 
+// import { Canvas } from "react-three-map" // if you are using MapBox
+
+function BasicExample() {
+  return <Map
+    antialias
+    initialViewState={{
+      latitude: 51,
+      longitude: 0,
+      zoom: 13,
+      pitch: 60
+    }}
+    mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json"
+  >
+    <Canvas latitude={51} longitude={0}>
+      <hemisphereLight
+        args={["#ffffff", "#60666C"]}
+        position={[1, 4.5, 3]}
+      />
+      <object3D scale={500}>
+        <Box position={[-1.2, 1, 0]} />
+        <Box position={[1.2, 1, 0]} />
+      </object3D>
+    </Canvas>
+  </Map>
+}
 ```
 
-## Documentation
+# Why we build this?
 
-For a full API reference, more usage examples, and other information, check out the full React [Three Map Documentation](#todo).
+Look [how complex](https://maplibre.org/maplibre-gl-js-docs/example/add-3d-model/) is to add just one ThreeJS object to a map.
 
-## Contributing
+Look [how complex](https://docs.pmnd.rs/react-three-fiber/api/canvas#createroot) is to create your custom root for R3F.
 
-We encourage you to contribute to React Three Map! Please check out the [Contributing to React Three Map guide](#todo) for guidelines about how to proceed.
+You can now replace all that complexity and hundreds of lines of code with the `<Canvas>` component exported by `react-three-map`, which includes a tone of extra features and seamless integration, supporting pointer events, raycasting, and much more, all out of the box.
 
-## License
+## API
 
-React Three Map is [MIT licensed](#todo).
+### Canvas
+
+Same as in `@react-three/fiber`, the `<Canvas>` object is where you start to define your React Three Fiber Scene. 
+
+```tsx
+import "maplibre-gl/dist/maplibre-gl.css"
+import Map from "react-map-gl/maplibre"
+import { Canvas } from 'react-three-map/maplibre'
+// import { Canvas } from "react-three-map" // if you are using MapBox
+
+const App = () => (
+  <Map 
+    initialViewState={{ latitude: 51, longitude: 0, zoom: 13 }} 
+    mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json" >
+    <Canvas latitude={51} longitude={0}>
+      <pointLight position={[10, 10, 10]} />
+      <mesh>
+        <sphereGeometry />
+        <meshStandardMaterial color="hotpink" />
+      </mesh>
+    </Canvas>
+  </Map>
+)
+```
 
-## Support
+It shares most of the props from R3F `<Canvas>`, so you can check them directly in the [`@react-three/fiber` docs](https://docs.pmnd.rs/react-three-fiber/api/canvas). There are a few important exceptions though, which are mentioned bellow.
 
-f you're having a problem with anything related to this library, we encourage you to reach out to us. We're always happy to help resolve issues and answer any questions you might have. Open an issue on our [Github repo](#todo).
+#### Render Props
 
-Remember to always follow the Code of Conduct when interacting with the community.
+| PROP       | DESCRIPTION                                      | DEFAULT  |
+| ---------  | ------------------------------------------------ | -------- |
+| latitude   | The latitude coordinate where to add the scene.  |          |
+| longitude  | The longitude coordinate where to add the scene. |          |
+| altitude   | The altitude coordinate where to add the scene.  | `0`      |
+| frameloop  | Render mode: always, demand.                     | `always` |
 
-## Enjoy Using React Three Map!
+#### Render Props removed from `@react-three/fiber`
 
-We hope that you enjoy using React Three Map as much as we enjoyed building it. Happy coding!
+Because the scene now lives in a map, we leave a lot of the render and camera control to the map, rather than to R3F.
 
-## Roadmap
+- gl
+- camera
+- resize
+- orthographic
+- dpr
 
-- [x] Use ThreeJS as a Map Layer (Maplibre).
-- [x] Support on demand rendering.
-- [ ] Use ThreeJS as a canvas overlay.
-- [ ] Add stencil buffers to occlude from the map.
-- [ ] Fully decompose the projection matrix into all the Camera properties required.
-- [ ] Support post processing.
-- [ ] Support multiple coordinate transformations using only one ThreeJS renderer.
-- [ ] Support `drei` `<Html>` component.
-- [ ] Support MapBox.
-- [ ] Support Google Maps.