From 6b2ec3d41c230cba2b30b7430ce9e0dbe607dbdd Mon Sep 17 00:00:00 2001 From: Aaron Date: Fri, 2 Aug 2024 16:08:01 +0800 Subject: [PATCH] docs: add coordinate docs (#6117) Co-authored-by: antv --- packages/g6/src/runtime/graph.ts | 10 ++--- .../manual/further-reading/coordinate.en.md | 43 ++++++++++++++++++- .../manual/further-reading/coordinate.zh.md | 41 +++++++++++++++++- 3 files changed, 87 insertions(+), 7 deletions(-) diff --git a/packages/g6/src/runtime/graph.ts b/packages/g6/src/runtime/graph.ts index 5da05e3040..3947544463 100644 --- a/packages/g6/src/runtime/graph.ts +++ b/packages/g6/src/runtime/graph.ts @@ -1382,9 +1382,9 @@ export class Graph extends EventEmitter { * Get the position of the graph * @returns 图的位置 | position of the graph * @remarks - * 默认状态下，图的位置为 [0, 0] + * 即画布原点在视口坐标系下的位置。默认状态下，图的位置为 [0, 0] * - * By default, the position of the graph is [0, 0] + * That is, the position of the canvas origin in the viewport coordinate system. By default, the position of the graph is [0, 0] * @apiCategory viewport */ public getPosition(): Point { @@ -1843,10 +1843,10 @@ export class Graph extends EventEmitter { } /** - * 获取画布中心的画布坐标 + * 获取视口中心的视口坐标 * - * Get the canvas coordinates of the canvas center - * @returns 画布中心的画布坐标 | Canvas coordinates of the canvas center + * Get the viewport coordinates of the viewport center + * @returns 视口中心的视口坐标 | Viewport coordinates of the viewport center * @apiCategory viewport */ public getCanvasCenter(): Point { diff --git a/packages/site/docs/manual/further-reading/coordinate.en.md b/packages/site/docs/manual/further-reading/coordinate.en.md index e471976ae8..1e0fec421f 100644 --- a/packages/site/docs/manual/further-reading/coordinate.en.md +++ b/packages/site/docs/manual/further-reading/coordinate.en.md @@ -3,4 +3,45 @@ title: coordinate order: 1 --- -Coming soon... +## Overview + +There are three coordinate systems in G6 5.0: Canvas, Viewport, and Client. + +### Canvas Coordinate System + +The coordinate system used when drawing G6 elements is not affected by camera zooming or panning. To change the position of an element, you need to directly modify the element's position properties (x/y/z). + +The canvas space is theoretically infinite. In the initial state (no panning, zoom ratio is 1), the origin of the canvas coordinate system is located at the upper-left corner of the viewport. + +### Viewport Coordinate System + +The viewport coordinate system is the projection of the camera coordinate system. When the camera pans or zooms, the position of elements in the canvas will also change in the viewport coordinate system. + +The size of the viewport is the size of the canvas DOM container. The origin of the viewport coordinate system is located at the upper-left corner of the viewport, with the x-axis pointing to the right and the y-axis pointing down. + +![viewport](https://developer.mozilla.org/en-US/Web/API/Canvas_API/Tutorial/Drawing_shapes/canvas_default_grid.png) + +### Client Coordinate System + +The client coordinate system has the browser's upper-left corner as the origin, with the x-axis pointing to the right and the y-axis pointing down. + +The following figure describes the relationship between the viewport coordinate system and the client coordinate system: + + + +## Coordinate System Conversion + +G6 provides methods for coordinate system conversion, making it easy to convert between different coordinate systems. + +- Canvas coordinate system to viewport coordinate system: [getViewportByCanvas](/en/api/graph/method#graphgetviewportbycanvaspoint) +- Client coordinate system to canvas coordinate system: [getCanvasByClient](/en/api/graph/method#graphgetcanvasbyclientpoint) +- Viewport coordinate system to canvas coordinate system: [getCanvasByViewport](/en/api/graph/method#graphgetcanvasbyviewportpoint) +- Canvas coordinate system to client coordinate system: [getClientByCanvas](/en/api/graph/method#graphgetclientbycanvaspoint) + +Other related APIs are also provided: + +- Get the viewport center in viewport coordinates: [getCanvasCenter](/en/api/graph/method#graphgetcanvascenter) +- Get the viewport center in canvas coordinates: [getViewportCenter](/en/api/graph/method#graphgetviewportcenter) +- Get the position of the graph origin in the viewport coordinate system: [getPosition](/en/api/graph/method#graphgetposition) + + diff --git a/packages/site/docs/manual/further-reading/coordinate.zh.md b/packages/site/docs/manual/further-reading/coordinate.zh.md index 3a89561ed5..934d50d90d 100644 --- a/packages/site/docs/manual/further-reading/coordinate.zh.md +++ b/packages/site/docs/manual/further-reading/coordinate.zh.md @@ -3,4 +3,43 @@ title: 坐标系 order: 1 --- -建设中... +## 概述 + +在 G6 5.0 中主要会涉及三个坐标系：画布坐标系(Canvas)、视口坐标系(Viewport)和浏览器坐标系(Client)。 + +### 画布坐标系 + +G6 元素绘制时所使用的坐标系，其不受相机缩放、平移的影响，要改变一个元素的位置，需要直接修改元素的位置属性(x/y/z)。 + +画布空间理论上是无限大的，在初始状态下（无平移、缩放倍率为1），画布坐标系的原点位于视口左上角位置。 + +### 视口坐标系 + +视口坐标系是相机坐标系的投影，当相机发生平移、缩放时，画布中元素位置在视口坐标系中的位置也会发生变化。 + +视口的大小即画布 DOM 容器的大小，视口坐标系的原点位于视口左上角位置，x 轴正方向向右，y 轴正方向向下。 + +![viewport](https://developer.mozilla.org/en-US/Web/API/Canvas_API/Tutorial/Drawing_shapes/canvas_default_grid.png) + +### 浏览器坐标系 + +浏览器坐标系以浏览器左上角为原点，x 轴正方向向右，y 轴正方向向下。 + +下图描述了视口坐标系和浏览器坐标系之间的关系： + + + +## 坐标系转换 + +G6 提供了坐标系转换的方法，可以方便地在不同坐标系之间进行转换。 + +- 画布坐标系转视口坐标系：[getViewportByCanvas](/api/graph/method#graphgetviewportbycanvaspoint) +- 浏览器坐标系转画布坐标系：[getCanvasByClient](/api/graph/method#graphgetcanvasbyclientpoint) +- 视口坐标系转画布坐标系：[getCanvasByViewport](/api/graph/method#graphgetcanvasbyviewportpoint) +- 画布坐标系转浏览器坐标系：[getClientByCanvas](/api/graph/method#graphgetclientbycanvaspoint) + +另外还提供了其他相关 API： + +- 获取视口中心的视口坐标：[getCanvasCenter](/api/graph/method#graphgetcanvascenter) +- 获取视口中心的画布坐标：[getViewportCenter](/api/graph/method#graphgetviewportcenter) +- 获取图原点在视口坐标系中的位置：[getPosition](/api/graph/method#graphgetposition)