Class CoordMap

Provides the mapping between screen (canvas) coordinates and simulation coordinates; this is an immutable object.

• Screen coordinates corresponds to pixels on an HTML canvas; the vertical coordinate increases going down, with zero usually being the top of the canvas.

• Simulation coordinates the vertical coordinate increases going up; units can be any size.

To create a CoordMap you specify translation and scaling factors for going between screen and simulation coordinates. The CoordMap constructor maps the bottom-left point on the canvas to the given bottom-left point in simulation space and then uses the given scaling factors.

The static method CoordMap.make calculates the translation and scaling factors in order to fit a certain rectangle in simulation coords into another rectangle in screen coords.

From David Flanagan, JavaScript: The Definitive Guide, 6th Edition page 869:

By default, the coordinate space for a canvas has its origin at `(0,0)` in the upper left corner of the canvas, with `x` values increasing to the right and `y` values increasing down. The `width` and `height` attributes of the `<canvas>` tag specify the maximum X and Y coordinates, and a single unit in this coordinate space normally translates to a single on-screen pixel.

Note however that a canvas actually has two coordinate systems:

The `<canvas...>` element is unlike almost all other HTML/HTML5 elements in using two different coordinate system scales simultaneously. The model coordinate system scale is used whenever you want to draw anything on the canvas. The display coordinate system scale is used to control how much physical screen space is dedicated to the canvas. You should explicitly specify both, the model coordinate size as attributes in your HTML, and the display coordinate size in your CSS.

Essentially the display coordinates can be used to stretch a canvas to fit the screen as desired. Here we ignore display coordinates and regard screen coordinates to be what is called model coordinates in the above quote.

Constructors

• Parameters

• screen_left: number

the left edge of the canvas in screen coordinates

• screen_bottom: number

the bottom edge of the canvas in screen coordinates

• sim_left: number

the simulation coordinate corresponding to screen_left

• sim_bottom: number

the simulation coordinate corresponding to screen_bottom

• pixel_per_unit_x: number

canvas pixels per simulation space unit along x axis

• pixel_per_unit_y: number

canvas pixels per simulation space unit along y axis

Methods

• Returns an AffineTransform that maps simulation coordinates to screen coordinates using the mapping defined by this CoordMap.

Returns AffineTransform

the AffineTransform equivalent of this CoordMap

• Returns the horizontal scaling factor: the screen pixels per simulation space unit along x axis.

Returns number

the horizontal scaling factor: screen pixels per unit of simulation space in x direction

• Returns the vertical scaling factor: the screen pixels per simulation space unit along y axis.

Returns number

the vertical scaling factor: screen pixels per unit of simulation space in y direction

• Translates a point in screen coordinates to simulation coordinates.

Parameters

• scr_x: number | GenericVector

horizontal position in screen coordinates, or GenericVector in screen coordinates

• `Optional`scr_y: number

vertical position in screen coordinates

Returns Vector

the equivalent position in simulation coordinates

• Translates the given screen coordinates rectangle into simulation coordinates.

Parameters

• rect: ScreenRect

the rectangle in screen coordinates

Returns DoubleRect

the equivalent rectangle in simulation coordinates

• Returns the equivalent length in simulation coordinates of the given horizontal length in screen coordinates.

Parameters

• scr_x: number

a horizontal length in screen coordinates

Returns number

the equivalent length in simulation coordinates

• Returns the equivalent length in simulation coordinates of the given vertical length in screen coordinates.

Parameters

• scr_y: number

a vertical length in screen coordinates

Returns number

the equivalent length in simulation coordinates

• Translates a horizontal screen coordinate to simulation coordinates.

Parameters

• scr_x: number

horizontal position in screen coordinates

Returns number

the equivalent position in simulation coordinates

• Translates a vertical screen coordinate to simulation coordinates.

Parameters

• scr_y: number

vertical position in screen coordinates

Returns number

the equivalent position in simulation coordinates

• Translates a point from simulation coordinates to screen coordinates.

Parameters

• p_sim: GenericVector

the point in simulation coordinates to translate

Returns Vector

the point translated to screen coordinates

• Translates the given simulation coordinates rectangle into screen coordinates.

Parameters

• r: DoubleRect

the rectangle in simulation coordinates

Returns ScreenRect

the equivalent rectangle in screen coordinates

• Returns the equivalent length in screen coordinates of the given horizontal length in simulation coordinates.

Parameters

• length_x: number

a horizontal length in simulation coordinates

Returns number

the equivalent length in screen coordinates

• Returns the equivalent length in screen coordinates of the given vertical length in simulation coordinates.

Parameters

• length_y: number

a vertical length in simulation coordinates

Returns number

the equivalent length in screen coordinates

• Translates a horizontal simulation coordinate to screen coordinates.

Parameters

• sim_x: number

horizontal position in simulation coordinates

Returns number

the equivalent position in screen coordinates

• Translates a vertical simulation coordinate to screen coordinates.

Parameters

• sim_y: number

vertical position in simulation coordinates

Returns number

the equivalent position in screen coordinates

• Creates a CoordMap that fits a simulation coordinates rectangle inside a screen coordinates rectangle in accordance with alignment options and aspect ratio. Calculates the origin and scale, which define the coordinate mapping.

The mapping is calculated so that the given simulation rectangle transforms to be the largest possible rectangle that fits inside the given screen rectangle, subject to various alignment options. The alignment options are similar to typical word processor alignment options such as left, center, right, or full justification. In the following diagrams the simulation rectangle is the smaller bold bordered rectangle, inside the larger screen rectangle.

``````┌──────────────────────────────────────────────────┐
│┏━━━━━━━━━━━━━━━━┓                                │
│┃                ┃                                │
│┃                ┃                                │
│┃    x: left     ┃                                │
│┃                ┃                                │
│┃                ┃                                │
│┗━━━━━━━━━━━━━━━━┛                                │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│               ┏━━━━━━━━━━━━━━━━┓                 │
│               ┃                ┃                 │
│               ┃                ┃                 │
│               ┃   x: middle    ┃                 │
│               ┃                ┃                 │
│               ┃                ┃                 │
│               ┗━━━━━━━━━━━━━━━━┛                 │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│                                ┏━━━━━━━━━━━━━━━━┓│
│                                ┃                ┃│
│                                ┃                ┃│
│                                ┃    x: right    ┃│
│                                ┃                ┃│
│                                ┃                ┃│
│                                ┗━━━━━━━━━━━━━━━━┛│
└──────────────────────────────────────────────────┘
``````

Both horizontal and vertical dimensions (x and y) have alignments. One of x or y will determine the scale and will fully span the screen rectangle; the alignment option only affects the other axis. In the diagrams above, the alignment of the y axis is ignored; the alignment only matters for the x placement.

Suppose the first diagram above had `LEFT` horizontal alignment and `TOP` vertical alignment, but then the screen rectangle changed to be tall and narrow; then we would see the first picture below. Other vertical alignment options are shown as well.

``````┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│┏━━━━━━━━━━━━━━━━┓│     │                  │     │                  │
│┃                ┃│     │                  │     │                  │
│┃    x: left     ┃│     │                  │     │                  │
│┃    y: top      ┃│     │                  │     │                  │
│┃                ┃│     │┏━━━━━━━━━━━━━━━━┓│     │                  │
│┃                ┃│     │┃                ┃│     │                  │
│┗━━━━━━━━━━━━━━━━┛│     │┃    x: left     ┃│     │                  │
│                  │     │┃    y: middle   ┃│     │                  │
│                  │     │┃                ┃│     │                  │
│                  │     │┃                ┃│     │┏━━━━━━━━━━━━━━━━┓│
│                  │     │┗━━━━━━━━━━━━━━━━┛│     │┃                ┃│
│                  │     │                  │     │┃    x: left     ┃│
│                  │     │                  │     │┃    y: bottom   ┃│
│                  │     │                  │     │┃                ┃│
│                  │     │                  │     │┃                ┃│
│                  │     │                  │     │┗━━━━━━━━━━━━━━━━┛│
└──────────────────┘     └──────────────────┘     └──────────────────┘
``````

`FULL` ensures that for the chosen axis the simulation and screen rectangles coincide. When both x and y have `FULL`, then the simulation and screen rectangles will coincide but the aspect ratio is altered, so an image from the simulation may appear squashed or stretched (see definition of aspect ratio below). For example, the square simulation rectangle from our earlier examples is stretched out here:

``````┌──────────────────────────────────────────────────┐
│┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓│
│┃                                                ┃│
│┃                                                ┃│
│┃             x:full, y:full                     ┃│
│┃                                                ┃│
│┃                                                ┃│
│┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛│
└──────────────────────────────────────────────────┘
``````

When only one of the axes has `FULL`, the simulation rectangle might not entirely fit into the screen rectangle as the following example shows, but the aspect ratio is preserved.

`````` ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                                                ┃
┃                                                ┃
┃                                                ┃
┃                                                ┃
┃                                                ┃
┌┃────────────────────────────────────────────────┃┐
│┃                                                ┃│
│┃                                                ┃│
│┃            x:full, y:middle                    ┃│
│┃                                                ┃│
│┃                                                ┃│
└┃────────────────────────────────────────────────┃┘
┃                                                ┃
┃                                                ┃
┃                                                ┃
┃                                                ┃
┃                                                ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
``````

The aspect ratio is the ratio of 'pixels per simulation unit along y axis' divided by 'pixels per simulation unit along x axis'. The default aspect ratio is 1.0, so x and y are treated identically with distance being measured the same in each direction. An aspect ratio other than 1.0 will squash or stretch the image. Note that aspect ratio is ignored when both x and y axes have `FULL` specified.

The simulation rectangle, screen rectangle, alignment options, and aspect ratio are only used to initially determine the coordinate transformation; they are not stored by the CoordMap.

Parameters

• screenRect: ScreenRect

the screen space rectangle to fit the sim rect into

• simRect: DoubleRect

the simulation space rectangle to be fit into the screenRect

• `Optional`horizAlign: LEFT | MIDDLE | RIGHT | FULL | VALUE

horizontal alignment option; default is `HorizAlign.MIDDLE`

• `Optional`verticalAlign: TOP | MIDDLE | BOTTOM | FULL | VALUE

vertical alignment option; default is`VerticalAlign.MIDDLE`

• `Optional`aspectRatio: number

the ratio of 'pixels per simulation unit along y axis' divided by 'pixels per simulation unit along x axis'; default is 1.0

Returns CoordMap

the CoordMap corresponding to the given options

Throws

if simRect is empty (has zero area), or invalid alignment options are given.

Generated using TypeDoc