@yandex/ymaps3-world-utils 0.0.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 YANDEX LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,81 @@
+# @yandex/ymaps3-world-utils
+
+Utility package for coordinate transformations in Yandex Maps 3.0.
+
+## Usage
+
+### ES Modules
+
+```bash
+npm install @yandex/ymaps3-world-utils
+```
+
+```javascript
+import { worldToPixels, pixelsToWorld } from '@yandex/ymaps3-world-utils';
+
+// Convert world coordinates to pixels
+const pixels = worldToPixels({ x: 0.5, y: 0.5 }, 10);
+console.log(pixels); // { x: 196608, y: 65536 }
+
+// Convert pixels back to world coordinates
+const world = pixelsToWorld({ x: 196608, y: 65536 }, 10);
+console.log(world); // { x: 0.5, y: 0.5 }
+```
+
+## API Reference
+
+### Coordinate Systems
+
+The package works with two coordinate systems:
+
+- **WorldCoordinates** - Normalized coordinates in the range `[-1, 1]`
+  - Center: `(0, 0)`
+  - Bottom-left corner: `(-1, -1)`
+  - Top-right corner: `(1, 1)`
+
+- **PixelCoordinates** - Global pixel coordinates
+  - World size depends on zoom level: `2^(zoom + 8) × 2^(zoom + 8)` pixels
+  - At zoom 0: 256×256 pixels
+  - At zoom 10: 262,144×262,144 pixels
+  - Top-left corner: `(0, 0)`
+  - Bottom-right corner: `(2^(zoom + 8), 2^(zoom + 8))`
+
+### Functions
+
+#### `worldToPixels(coordinates: WorldCoordinates, zoom: number): PixelCoordinates`
+
+Converts world coordinates to pixel coordinates.
+
+**Parameters:**
+- `coordinates` - World coordinates object with `x` and `y` properties
+- `zoom` - Zoom level (integer)
+
+**Returns:** Pixel coordinates object with `x` and `y` properties
+
+**Example:**
+```javascript
+const pixels = worldToPixels({ x: 0, y: 0 }, 10);
+// Returns: { x: 131072, y: 131072 } - center of the world at zoom 10
+```
+
+---
+
+#### `pixelsToWorld(pixels: PixelCoordinates, zoom: number): WorldCoordinates`
+
+Converts pixel coordinates to world coordinates.
+
+**Parameters:**
+- `pixels` - Pixel coordinates object with `x` and `y` properties
+- `zoom` - Zoom level (integer)
+
+**Returns:** World coordinates object with `x` and `y` properties
+
+**Example:**
+```javascript
+const world = pixelsToWorld({ x: 131072, y: 131072 }, 10);
+// Returns: { x: 0, y: 0 } - center of the world
+```
+
+## License
+
+Apache-2.0

package/dist/esm/index.d.ts

@@ -0,0 +1,34 @@
+interface Vec2 {
+    x: number;
+    y: number;
+}
+
+/**
+ * Coordinates in [-1 ... +1].
+ * Left bottom is (-1; -1).
+ * Right top is (+1; +1).
+ * Center is (0; 0).
+ */
+interface WorldCoordinates extends Vec2 {
+    readonly type?: 'world';
+    z?: number;
+}
+/**
+ * Global pixel coordinates. World size depends on zoom.
+ * Left top is (0; 0).
+ * Right bottom is (2**(zoom + 8); 2**(zoom + 8)).
+ */
+interface PixelCoordinates extends Vec2 {
+    readonly type?: 'pixel';
+}
+
+/**
+ * Converts world coordinates to pixel coordinates. Pixels are in (0, 0) (width, height) range.
+ */
+declare function worldToPixels(coordinates: WorldCoordinates, zoom: number): PixelCoordinates;
+/**
+ * Converts pixels in (0, 0) (width, height) to world coordinates.
+ */
+declare function pixelsToWorld(pixels: PixelCoordinates, zoom: number): WorldCoordinates;
+
+export { pixelsToWorld, worldToPixels };

package/dist/esm/index.js

@@ -0,0 +1 @@
+var i=t(0,0);function t(e,r){return{x:e,y:r}}function n(e,r,o=t(0,0)){return o.x=e.x*r,o.y=e.y*r,o}var{cos:d,sin:s}=Math;var c=256;function x(e,r){let o=2**r/2*c;return n({x:e.x+1,y:1-e.y},o)}function l(e,r){let o=2**r/2*c;return{x:e.x/o-1,y:1-e.y/o}}export{l as pixelsToWorld,x as worldToPixels};

package/dist/index.js

@@ -0,0 +1 @@
+!function(e,o){"object"==typeof exports&&"object"==typeof module?module.exports=o():"function"==typeof define&&define.amd?define([],o):"object"==typeof exports?exports["@yandex/ymaps3-world-utils"]=o():e["@yandex/ymaps3-world-utils"]=o()}(this,()=>(()=>{"use strict";var e={d:(o,t)=>{for(var n in t)e.o(t,n)&&!e.o(o,n)&&Object.defineProperty(o,n,{enumerable:!0,get:t[n]})},o:(e,o)=>Object.prototype.hasOwnProperty.call(e,o),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},o={};function t(e,o){return{x:e,y:o}}e.r(o),e.d(o,{pixelsToWorld:()=>u,worldToPixels:()=>i}),t(0,0);const{cos:n,sin:r}=Math,y=256;function i(e,o){const n=2**o/2*y;return function(e,o,n=t(0,0)){return n.x=e.x*o,n.y=e.y*o,n}({x:e.x+1,y:1-e.y},n)}function u(e,o){const t=2**o/2*y;return{x:e.x/t-1,y:1-e.y/t}}return o})());

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@yandex/ymaps3-world-utils",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/esm/index.js",
+  "module": "./dist/esm/index.js",
+  "unpkg": "./dist/index.js",
+  "jsdelivr": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "browser": "./dist/index.js",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && webpack --config webpack.config.cjs"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "webpack": "^5.88.0",
+    "webpack-cli": "^5.1.0",
+    "ts-loader": "^9.4.0"
+  },
+  "sideEffects": false,
+  "bugs": {
+    "url": "https://yandex.ru/maps-api/docs/js-api/feedback/troubleshooting.html"
+  },
+  "homepage": "https://yandex.ru/maps-api/docs/js-api/index.html",
+  "license": "Apache-2.0",
+  "description": "Yandex Maps 3 World Utilities - coordinate transformation functions",
+  "keywords": [
+    "ymaps3",
+    "api",
+    "map",
+    "ymaps",
+    "js api"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}