location parameters document

`location` Parameter Documentation

Parameter Name

location

Data Type

Array[Array[float, float]]

The outer array must have a fixed length of 4 (must contain 4 vertices)

The inner array must have a fixed length of 2 (each vertex contains [x, y] coordinates)

Description

Represents the position and orientation of a shape on the canvas. The rectangle (including rotated rectangles) is defined by four vertex coordinates. The vertices must be listed in continuous clockwise order (recommended; all examples and code use clockwise order):

Left Top (left_top)

Right Top (right_top)

Right Bottom (right_bottom)

Left Bottom (left_bottom)

The coordinate system uses normalized coordinates for adaptive support across different canvas resolutions:

Origin (0, 0): Top-left corner of the canvas

Bottom-right (1, 1): Bottom-right corner of the canvas

Coordinate range: unrestricted (values outside [0, 1] indicate the shape is partially outside the canvas)

Normalization formula (actual coordinate → normalized coordinate):

  normalized_x = actual_x / canvas_width
  normalized_y = actual_y / canvas_height

For example, actual coordinate (200, 100) on a 1000×500 canvas is normalized to (0.2, 0.2).

Vertex Order and Meaning

Index	Vertex Name	Description	Example `[x, y]`
`0`	`left_top`	Top-left vertex	`[0.2, 0.2]`
`1`	`right_top`	Top-right vertex	`[0.6, 0.2]`
`2`	`right_bottom`	Bottom-right vertex	`[0.6, 0.6]`
`3`	`left_bottom`	Bottom-left vertex	`[0.2, 0.6]`

📌 Key Rules:
Vertices must be listed in continuous clockwise or counterclockwise order to form a closed rectangle (if using counterclockwise, ensure the order is continuous and closed; otherwise, rotation and other operations may not work as expected)
Coordinate values may exceed [0, 1], indicating the shape is partially outside the canvas (as long as any part is inside, it is considered valid)

Example Values

The black box represents the valid canvas area; x and y are normalized values relative to the actual width and height.

A rectangle fully inside the canvas:

{
  "location": [
    [0.2, 0.2],  // left_top
    [0.6, 0.2],  // right_top
    [0.6, 0.6],  // right_bottom
    [0.2, 0.6]   // left_bottom
  ]
}

A rectangle partially outside the canvas

{
  "location": [
    [-0.2, -0.2],  // left_top
    [0.2, -0.2],   // right_top
    [0.2, 0.2],    // right_bottom
    [-0.2, 0.2]    // left_bottom
  ]
}

Rectangle from Example 1 rotated 45 degrees clockwise

"location": [
   [0.4, 0.1172],   // left_top
   [0.6828, 0.4],   // right_top
   [0.4, 0.6828],   // right_bottom
   [0.1172, 0.4]    // left_bottom
]

Sample code for calculating rotated coordinates:

A positive rotation angle means clockwise; negative means counterclockwise.

Sample Code: Strictly Checking If Four Vertices (Fixed Order) Form a Rectangle

📌 Notes:
The vertex order must be strictly: left_top, right_top, right_bottom, left_bottom.
Incorrect order will return false.
Supports rotation and normalized coordinates.

Notes

The vertex order must be strictly maintained; otherwise, operations like rotation and rendering may not work as expected.

Normalized coordinates are suitable for responsive and multi-resolution canvas scenarios.

Coordinates can exceed [0, 1] as long as any part of the shape is within the canvas.

Let me know if you need a concise version or OpenAPI schema!

location Parameter Documentation#

Parameter Name#

Data Type#

Description#

Vertex Order and Meaning#

Example Values#

Sample Code: Strictly Checking If Four Vertices (Fixed Order) Form a Rectangle#

Notes#