ianmackenzie / elm-units-prefixed / Units.Pixels

Although most of the focus of elm-units is on physical/scientific units, it's often useful to be able to safely convert back and forth between (for example) Length values in the real world and on-screen lengths in pixels.

This module provides a standard Pixels units type and basic functions for constructing/converting values of type Quantity Int Pixels or Quantity Float Pixels, which allows you to do things like represent conversions between real-world and on-screen lengths as rates of change. This in turn means that all the normal Quantity functions can be used to convert between pixels and other units, or even do type-safe math directly on pixel values.


type alias Pixels =
Pixels

Units type representing one on-screen pixel.

int : Basics.Int -> Quantity Basics.Int Pixels

Construct a quantity representing an integer number of on-screen pixels:

screenWidth =
    Pixels.int 1920

float : Basics.Float -> Quantity Basics.Float Pixels

Construct a quantity representing a floating-point number of on-screen pixels:

lineWeight =
    Pixels.float 1.5

toInt : Quantity Basics.Int Pixels -> Basics.Int

Convert an integer number of pixels back into a plain Int:

Pixels.int 1920
    |> Quantity.multiplyBy 2
    |> Pixels.toInt
--> 3840

toFloat : Quantity Basics.Float Pixels -> Basics.Float

Convert a floating-point number of pixels back into a plain Float:

pixelDensity =
    Pixels.float 96 |> Quantity.per (Length.inches 1)

Length.centimeters 1
    |> Quantity.at pixelDensity
    |> Pixels.toFloat
--> 37.795275590551185

pixels : number -> Quantity number Pixels

Generic version of Pixels.int/Pixels.float, for consistency with other modules like Length. Note that passing an Int will give you a

Quantity Int Pixels

while passing a Float will give you a

Quantity Float Pixels

If you pass a literal integer like 1920, you will get a generic Quantity number Pixels which can be used as either an Int or Float number of pixels.

inPixels : Quantity number Pixels -> number

Convert a Pixels value to a plain number of pixels. This is a generic version of Pixels.toInt/Pixels.toFloat.

pixel : Quantity number Pixels

Shorthand for Pixels.pixels 1. Can be convenient to use with Quantity.per.

Rates


type alias PixelsPerSecond =
PixelsPerSecond

Units type representing an on-screen speed of one pixel per second.


type alias PixelsPerSecondSquared =
PixelsPerSecondSquared

Units type representing an on-screen acceleration of one pixel per second squared.

pixelsPerSecond : Basics.Float -> Quantity Basics.Float PixelsPerSecond

Construct an on-screen speed from a number of pixels per second.

inPixelsPerSecond : Quantity Basics.Float PixelsPerSecond -> Basics.Float

Convert an on-screen speed to a number of pixels per second.

elapsedTime =
    Duration.milliseconds 16

dragDistance =
    Pixels.float 2

dragSpeed =
    dragDistance |> Quantity.per elapsedTime

dragSpeed |> Pixels.inPixelsPerSecond
--> 125

pixelsPerSecondSquared : Basics.Float -> Quantity Basics.Float PixelsPerSecondSquared

Construct an on-screen acceleration from a number of pixels per second squared.

inPixelsPerSecondSquared : Quantity Basics.Float PixelsPerSecondSquared -> Basics.Float

Convert an on-screen acceleration to a number of pixels per second squared.

Areas


type alias SquarePixels =
Pixels.SquarePixels

Units type representing an on-screen area of one square pixel. For example, a 32x32 image has an area of 1024 square pixels.

squarePixels : number -> Quantity number Pixels.SquarePixels

Construct an on-screen area from a number of square pixels.

inSquarePixels : Quantity number Pixels.SquarePixels -> number

Convert an on-screen area to a number of square pixels.

area =
    Pixels.int 1928 |> Quantity.times (Pixels.int 1080)

area |> Pixels.inSquarePixels
--> 2073600