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.

Index

Constructors

constructor

Methods

getAffineTransform getScaleX getScaleY screenToSim screenToSimRect screenToSimScaleX screenToSimScaleY screenToSimX screenToSimY simToScreen simToScreenRect simToScreenScaleX simToScreenScaleY simToScreenX simToScreenY toString make

Constructors

constructor

new CoordMap(screen_left, screen_bottom, sim_left, sim_bottom, pixel_per_unit_x, pixel_per_unit_y): CoordMap
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
Returns CoordMap
- Defined in lab/view/CoordMap.ts:84

Methods

getAffineTransform

getAffineTransform(): AffineTransform
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
- Defined in lab/view/CoordMap.ts:348

getScaleX

getScaleX(): number
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
- Defined in lab/view/CoordMap.ts:357

getScaleY

getScaleY(): number
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
- Defined in lab/view/CoordMap.ts:366

screenToSim

screenToSim(scr_x, scr_y?): Vector
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
- Defined in lab/view/CoordMap.ts:376

screenToSimRect

screenToSimRect(rect): DoubleRect
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
- Defined in lab/view/CoordMap.ts:396

screenToSimScaleX

screenToSimScaleX(scr_x): number
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
- Defined in lab/view/CoordMap.ts:410

screenToSimScaleY

screenToSimScaleY(scr_y): number
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
- Defined in lab/view/CoordMap.ts:419

screenToSimX

screenToSimX(scr_x): number
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
- Defined in lab/view/CoordMap.ts:427

screenToSimY

screenToSimY(scr_y): number
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
- Defined in lab/view/CoordMap.ts:435

simToScreen

simToScreen(p_sim): Vector
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
- Defined in lab/view/CoordMap.ts:443

simToScreenRect

simToScreenRect(r): ScreenRect
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
- Defined in lab/view/CoordMap.ts:451

simToScreenScaleX

simToScreenScaleX(length_x): number
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
- Defined in lab/view/CoordMap.ts:465

simToScreenScaleY

simToScreenScaleY(length_y): number
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
- Defined in lab/view/CoordMap.ts:474

simToScreenX

simToScreenX(sim_x): number
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
- Defined in lab/view/CoordMap.ts:482

simToScreenY

simToScreenY(sim_y): number
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
- Defined in lab/view/CoordMap.ts:490

toString

toString(): string
Returns string
Inherit Doc
- Defined in lab/view/CoordMap.ts:101

`Static` make

make(screenRect, simRect, horizAlign?, verticalAlign?, aspectRatio?): CoordMap

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 isVerticalAlign.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.

Class CoordMap

Index

Constructors

Methods

Constructors

constructor

Parameters

screen_left: number

screen_bottom: number

sim_left: number

sim_bottom: number

pixel_per_unit_x: number

pixel_per_unit_y: number

Returns CoordMap

Methods

getAffineTransform

Returns AffineTransform

getScaleX

Returns number

getScaleY

Returns number

screenToSim

Parameters

scr_x: number | GenericVector

Optional scr_y: number

Returns Vector

screenToSimRect

Parameters

rect: ScreenRect

Returns DoubleRect

screenToSimScaleX

Parameters

scr_x: number

Returns number

screenToSimScaleY

Parameters

scr_y: number

Returns number

screenToSimX

Parameters

scr_x: number

Returns number

screenToSimY

Parameters

scr_y: number

Returns number

simToScreen

Parameters

p_sim: GenericVector

Returns Vector

simToScreenRect

Parameters

r: DoubleRect

Returns ScreenRect

simToScreenScaleX

Parameters

length_x: number

Returns number

simToScreenScaleY

Parameters

length_y: number

Returns number

simToScreenX

Parameters

sim_x: number

Returns number

simToScreenY

Parameters

sim_y: number

Returns number

toString

Returns string

Inherit Doc

Static make

Parameters

screenRect: ScreenRect

simRect: DoubleRect

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

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

Optional aspectRatio: number

`Optional` scr_y: number

`Static` make

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

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

`Optional` aspectRatio: number