react-three-map 0.8.1 → 1.0.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # react-three-map
 
+## 1.0.0-next.0
+
+### Major Changes
+
+- 9be6c41: Updated to work with `react-map-gl >= 8.0.0`.
+
+  This has the cascade effect of requiring also to upgrade either of the map providers you are using:
+
+  - `mapbox-gl >= 3.5.0`
+  - `maplibre-gl >= 4.0.0`
+
+## 0.8.2
+
+### Patch Changes
+
+- 58c42d9: - Improve accuracy at long distances for `coordsToVector3`.
+  - Improve translation accuracy for `NearCoordinates`, but scale is still ignored.
+  - Update `earthRadius` from `6378137` to `6371008.8` to match [Mapbox](https://github.com/maplibre/maplibre-gl-js/blob/8ea76118210dd18fa52fdb83f2cbdd1229807346/src/geo/lng_lat.ts#L8) and [Maplibre](https://github.com/maplibre/maplibre-gl-js/blob/main/src/geo/lng_lat.ts#L8).
+
 ## 0.8.1
 
 ### Patch Changes

package/README.md

@@ -11,10 +11,10 @@
 
 Until now you had:
 
-| imperative | declarative (react)    |
-| --------------- | ----------------- |
-| Maplibre/Mapbox | react-map-gl      |
-| THREE.js        | react-three-fiber |
+| imperative      | declarative (react) |
+| --------------- | ------------------- |
+| Maplibre/Mapbox | react-map-gl        |
+| THREE.js        | react-three-fiber   |
 
 Now with `react-three-map`, you can use them together :fist_right::star::fist_left:.
 
@@ -22,6 +22,21 @@ Now with `react-three-map`, you can use them together :fist_right::star::fist_le
 npm install react-three-map
 ```
 
+- [React Three Map](#react-three-map)
+  - [:book: Examples](#book-examples)
+  - [:mag: What does it look like?](#mag-what-does-it-look-like)
+  - [:thinking: Why we build this?](#thinking-why-we-build-this)
+  - [:gear: API](#gear-api)
+    - [Canvas](#canvas)
+      - [Render Props](#render-props)
+      - [Render Props removed from `@react-three/fiber`](#render-props-removed-from-react-threefiber)
+    - [Coordinates](#coordinates)
+    - [NearCoordinates](#nearcoordinates)
+    - [useMap](#usemap)
+    - [coordsToVector3](#coordstovector3)
+    - [vector3ToCoords](#vector3tocoords)
+
+
 ## :book: Examples
 
 Check out our examples [here](https://rodrigohamuy.github.io/react-three-map) (powered by [Ladle](https://ladle.dev/)).
@@ -32,9 +47,9 @@ Check out our examples [here](https://rodrigohamuy.github.io/react-three-map) (p
 <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>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/react-three-map-gettings-started-dhw34w">live demo</a>).</td>
       <td>
-        <a href="https://codesandbox.io/p/sandbox/vigorous-snyder-2n9vpl?file=%2Fsrc%2FApp.tsx%3A48%2C45">
+        <a href="https://codesandbox.io/p/sandbox/react-three-map-gettings-started-dhw34w">
           <img src="docs/basic-app.gif" />
         </a>
       </td>
@@ -120,13 +135,13 @@ It shares most of the props from R3F `<Canvas>`, so you can check them directly
 
 #### Render Props
 
-| 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"` |
-| overlay    | Render on a separated canvas.                    | `false`    |
+| 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"` |
+| overlay   | Render on a separated canvas.                    | `false`    |
 
 **About `overlay`**
 
@@ -172,21 +187,21 @@ import { Canvas, Coordinates } from 'react-three-map'
 </Canvas>
 ```
 
-| Props       | 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`        |
+| Props     | 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`     |
 
 ### NearCoordinates
 
 [![](https://img.shields.io/badge/-demo-%23ff69b4)](https://rodrigohamuy.github.io/react-three-map/?story=multi-coordinates--default)
 
-Same as `Coordinates`, but with an error margin that increases the further you are from the origin.
+Same as `Coordinates`, but scale is ignored in exchange of being able to be rendered under the same scene.
 
-Recommended to use at city level distances, but margin errors will be noticeable at country level distances.
+Works well at city level distances, but since scale remains unchanged, is not recommended at country level distances.
 
-Check the story to see the difference between the two.
+Check the story to see the difference between the two or check #102 for more info.
 
 ### useMap
 
@@ -208,7 +223,7 @@ const Component = () => {
 
 This utility function converts geographic coordinates into a `Vector3Tuple`, which represents a 3D vector in meters.
 
-Similar to `NearCoordinates` it has a relatively good precision at city distances, but is not recommended if your distances are too big.
+Similar to `NearCoordinates`, remember that this only updates positions (translation) but that scale is not taken into account, which has an important factor at very long distances (country level).
 
 
 | Parameter        | Description                                                     |
@@ -224,11 +239,13 @@ Returns a `Vector3Tuple` representing the 3D position of the point relative to t
 
 This utility function converts a `Vector3Tuple`, which represents a 3D vector in meters, back into geographic coordinates.
 
-It is the inverse of `coordsToVector3` and maintains the same level of precision. It is not recommended for use with very large distances.
+It is the inverse of `coordsToVector3` but it does not have a good level of precision at long distances since we haven't reverse engineered #102 fix yet.
+
+Recommended to use at city level distances, but margin errors will be noticeable at country level distances.
 
 | Parameter                | Description                                                     |
 | ------------------------ | --------------------------------------------------------------- |
 | `position: Vector3Tuple` | The 3D vector to convert back into geographic coordinates.      |
 | `origin: Coords`         | The geographic coordinates used as the origin for calculations. |
 
-Returns a `Coords` object representing the geographic coordinates of the point relative to the origin.
+Returns a `Coords` object representing the geographic coordinates of the point relative to the origin.