O1Library Docs
Fall 2023
Docs API

# Pic

o1.gui.Pic
See the Pic companion object
final class Pic extends HasAnchor

Each instance of this class represents a picture: an immutable two-dimensional image.

You don’t instantiate `Pic` directly; instead, you create `Pic`s with the methods on the `Pic` companion object. For instance, you can:

- load existing images: `Pic("mypic.png")` or `Pic("http://address.of/mypic.png")`),
- create `Pic`s of shapes (e.g., `circle(150, Red)` or `star(100, Black)`); or
- generate the pixels of a `Pic` with a function.

Moreover, many of the methods of a `Pic` object create and return new `Pic`s that represent combinations or transformations of existing `Pic`s.

This class has an alias in the top-level package o1, so it’s accessible to students simply via `import o1.*`.

The examples below illustrate a few of the methods (assuming the above import):

    val background = rectangle(400, 300, Red)
    val rotatedSquare = square(50, Blue).clockwise(30)
    val squareAgainstBg = background.place(rotatedSquare, Pos(100, 100))
    squareAgainstBg.show()

    val ladybug = Pic("ladybug.png").scaleTo(100).flipHorizontal
    val combination = circle(100, Red).leftOf(ladybug)
    val part = combination.crop(Pos(10, 10), 180, 80)
    val negative = part.transformColors( _.negative )
    negative.show()

Some of the methods of a `Pic` that use Pos objects or plain x and y coordinates to indicate positions within the `Pic` (e.g., `place` and `crop` above). All these methods consider the origo to be at the top left-hand corner or the `Pic`, with x values increasing downwards and y values rightwards. The coordinates are in pixels.

Each image has an anchor that defines where it connects to other `Pic`s. By default, the anchor is Center; for example, the `place` method call above puts the center of the square at `Pos(100, 100)` within the background.

Here is a of the main types of operations as methods on a `Pic`, and examples of each type:

- Combining `Pic`s by positioning them relative to each other: `above`, `below`, `leftOf`, `rightOf`, `onto`, `against`, `place`.

- Rotations (*): `clockwise`, `counterclockwise`

- Changing size (*): `scaleBy`, `scaleTo`

- Selecting and moving pixels (**): `crop`, `shift`, `flipHorizontal`, `flipVertical`

- Examining and manipulating individual pixels (**): `pixelColor`, `transformXY`, `transformColors`, `combine`

- Convenience methods for experimentation and debugging: `show`, `hide`.

### Notes on implementation and efficiency:

Internally, a `Pic` stores its contents either as vector-based graphics, as a bitmap (raster), or as a combination of the two. By design, that internal representation is meant to be largely opaque to the user of the `Pic` class: students in O1 working on O1’s standard assignments generally shouldn’t need to know or care about it. Nevertheless, whether a particular `Pic` is stored in vector or bitmap form does have very substantial effect on efficiency in some contexts; `Pic`, like the rest of O1Library, is not designed for high-performance graphics.

Some users of this class may wish to know the following:

- `Pic`s start out in either vector form or bitmap form, depending on which method created them. Specifically, the shape-creating methods (like `rectangle` and `circle`). produce `Pic`s in vector form.

- No operation on a `Pic` ever changes an already rasterized bitmap into vector graphics. (An operation such as `leftOf` can produce an `Pic` that is stored as a combination of a vector graphic and a bitmap.)

- Some operations always produce a rasterized `Pic`. These are marked with a double asterisk (**) in the list above. Some operations sometimes produce rasterized `Pic`s but may retain the vector-based representation in simple cases. These are marked with a single asterisk (*).

- You can call freeze to force rasterization.

## Attributes

Companion
  object
Graph
Supertypes
  trait HasAnchor
  trait HasSize
  class Object
  trait Matchable
  class Any

## Members list

### Value members

#### Concrete methods

infix def above(lowerPic: Pic, retainAnchor: Boolean): Pic

Combines this `Pic` and the given one so that this `Pic` appears immediately above the other `Pic`. The combined `Pic` will be large enough to fit both originals.

Combines this `Pic` and the given one so that this `Pic` appears immediately above the other `Pic`. The combined `Pic` will be large enough to fit both originals.

## Parameters

lowerPic

  the `Pic` that is below this `Pic` in the combination

retainAnchor

  `true` means that the anchor of the combination should be equally far from the top left-hand corner as this `Pic`’s anchor is; `false` (the default) means that the combination should follow the same general anchoring policy has this `Pic` (e.g., to anchor from its center). If unspecified, defaults to `false`.

## Attributes

Returns

  the combined `Pic`

See also

  below, leftOf, rightOf, columnOf

def absoluteAnchor: Anchor

An Anchor.Absolute that points to the same spot in the `Pic` that the `Pic`’s current anchor does.

An Anchor.Absolute that points to the same spot in the `Pic` that the `Pic`’s current anchor does.

## Attributes

def against(background: Pic, at: Pos): Pic

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` anchors this `Pic` at its default anchor to a specific Pos in the background.

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` anchors this `Pic` at its default anchor to a specific Pos in the background.

## Parameters

at

  the point within `background` that this `Pic`’s anchor is positioned at

background

  a `Pic` that serves as a background for this one and determines the size of the visible part of the resulting image

## Attributes

Returns

  the combined `Pic`

See also

  `onto`, which does the same but doesn’t leave out the “hanging” parts of the foreground image

  `place`, which does the same but switches the order of the two `Pic`s

def against(background: Pic, my: Anchor, at: Pos): Pic

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` uses the given Anchor instead of this `Pic`s default `anchor` and places it at a specific Pos in the background.

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` uses the given Anchor instead of this `Pic`s default `anchor` and places it at a specific Pos in the background.

## Parameters

at

  the point within `background` that this `Pic` is positioned at

background

  a `Pic` that serves as a background for this one and determines the size of the visible part of the resulting image

my

  the point within this `Pic` that will be placed at the given coordinates

## Attributes

Returns

  the combined `Pic`

See also

  `onto`, which does the same but doesn’t leave out the “hanging” parts of the foreground image

  `place`, which does the same but switches the order of the two `Pic`s

def against(background: Pic, my: Anchor, atIts: Anchor): Pic

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` uses the given Anchors instead of the default `anchor` of either of the original `Pic`s.

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` uses the given Anchors instead of the default `anchor` of either of the original `Pic`s.

## Parameters

atIts

  the point within `background` that this `Pic` is positioned at

background

  a `Pic` that serves as a background for this one and determines the size of the visible part of the resulting image

my

  the point within this `Pic` that will be placed at the given coordinates

## Attributes

Returns

  the combined `Pic`

See also

  `onto`, which does the same but doesn’t leave out the “hanging” parts of the foreground image

  `place`, which does the same but switches the order of the two `Pic`s

infix def against(background: Pic, atIts: Anchor): Pic

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` anchors this `Pic` at its default anchor to an anchor in the background.

Combines this `Pic` and the given one so that the other `Pic` serves as a background and this `Pic` appears in front of it but not beyond its borders. The visible part of the combined `Pic` is the size of the background `Pic`. In the combination, some or even none of this `Pic` is visible in front of the background, depending on the relative positioning and dimensions of the two images; any parts of this `Pic` that don’t fit against the background are left out. (The left-out parts are still part of the `Pic`’s data but not visible; only the part within the framing background image will be shown when the `Pic` is rendered onscreen.) This version of `against` anchors this `Pic` at its default anchor to an anchor in the background.

## Parameters

atIts

  the point within `background` that this `Pic`’s anchor is positioned at; if unspecified, defaults to Center

background

  a `Pic` that serves as a background for this one and determines the size of the visible part of the resulting image

## Attributes

Returns

  the combined `Pic`

See also

  `onto`, which does the same but doesn’t leave out the “hanging” parts of the foreground image

  `place`, which does the same but switches the order of the two `Pic`s

def alternatingColumn(another: Pic, number: Int): Pic

Combines copies of this `Pic` and another `Pic` so that they alternate in a vertical column (starting with this `Pic`). The combined `Pic` will be large enough to fit all the copies.

Combines copies of this `Pic` and another `Pic` so that they alternate in a vertical column (starting with this `Pic`). The combined `Pic` will be large enough to fit all the copies.

## Parameters

number

  the total number of `Pic`s in the column (e.g., 6 means the result has three copies of each `Pic`)

## Attributes

See also

  above, below, columnOf, alternatingRow

def alternatingRow(another: Pic, number: Int): Pic

Combines copies of this `Pic` and another `Pic` so that they alternate in a horizontal row (starting with this `Pic`). The combined `Pic` will be large enough to fit all the copies.

Combines copies of this `Pic` and another `Pic` so that they alternate in a horizontal row (starting with this `Pic`). The combined `Pic` will be large enough to fit all the copies.

## Parameters

number

  the total number of `Pic`s in the row (e.g., 6 means the result has three copies of each `Pic`)

## Attributes

See also

  leftOf, rightOf, rowOf, alternatingColumn

def anchorAt(anchor: Anchor): Pic

Anchors the `Pic` at the given position.

Anchors the `Pic` at the given position.

## Parameters

anchor

  a new anchoring position

## Attributes

Returns

  a new `Pic` that’s identical to the original but anchored at the given position

def apply(pixelX: Int, pixelY: Int): Color

Returns the color of the pixel at the given coordinates within the image. (This is equivalent to calling `pixelColor`.)

Returns the color of the pixel at the given coordinates within the image. (This is equivalent to calling `pixelColor`.)

The given position must be within the image’s bounds; an out-of-bounds error will occur otherwise.

N.B. This is inefficient on a `Pic` that’s not fully rasterized as a bitmap. If you have a vector graphic and need to call this method many times, consider freezing the `Pic` first.

## Attributes

def apply(pixelPos: Pos): Color

Returns the color of the pixel at the given coordinates within the image. (This is equivalent to calling `pixelColor`.)

Returns the color of the pixel at the given coordinates within the image. (This is equivalent to calling `pixelColor`.)

The given position must be within the image’s bounds; an out-of-bounds error will occur otherwise.

N.B. This is inefficient on a `Pic` that’s not fully rasterized as a bitmap. If you have a vector graphic and need to call this method many times, consider freezing the `Pic` first.

## Attributes

infix def below(abovePic: Pic, retainAnchor: Boolean): Pic

Combines this `Pic` and the given one so that this `Pic` appears immediately below the other `Pic`. The combined `Pic` will be large enough to fit both originals.

Combines this `Pic` and the given one so that this `Pic` appears immediately below the other `Pic`. The combined `Pic` will be large enough to fit both originals.

## Parameters

abovePic

  the `Pic` that is above this `Pic` in the combination

retainAnchor

  `true` means that the anchor of the combination should be equally far from the top left-hand corner as this `Pic`’s anchor is; `false` (the default) means that the combination should follow the same general anchoring policy has this `Pic` (e.g., to anchor from its center). If unspecified, defaults to `false`.

## Attributes

Returns

  the combined `Pic`

See also

  above, leftOf, rightOf, columnOf

def clockwise(degrees: Double): Pic

Creates version of this `Pic` that’s rotated clockwise around its center. The resulting image is sized so that the entire contents of the original `Pic` are visible; any empty space in the corners is Transparent.

Creates version of this `Pic` that’s rotated clockwise around its center. The resulting image is sized so that the entire contents of the original `Pic` are visible; any empty space in the corners is Transparent.

## Parameters

degrees

  the amount of clockwise rotation, in degrees; if unspecified, defaults to 90.0

## Attributes

Returns

  a new `Pic` that is a rotated version of this one; it will usually be a bitmap, but some simple vector-based `Pic`s may retain their vector form

def columnOf(number: Int): Pic

Combines copies of this `Pic` so that they appear in a vertical column. The combined `Pic` will be large enough to fit all the copies.

Combines copies of this `Pic` so that they appear in a vertical column. The combined `Pic` will be large enough to fit all the copies.

## Parameters

number

  the number of copies in the column (e.g., 3 means the result has three identical images)

## Attributes

See also

  above, below, rowOf, alternatingColumn

def combine(another: Pic, determinePixel: (Color, Color) => Color): Pic

Creates a new `Pic` by combining this `Pic` with the given one on a pixel-by-pixel basis. For each pair of pixel coordinates in the two original `Pic`s, `combine` calls the given function to compute the color of the corresponding pixel in the new `Pic`. The new `Pic`’s width equals the lesser of the two originals’ widths; the same goes for height.

Creates a new `Pic` by combining this `Pic` with the given one on a pixel-by-pixel basis. For each pair of pixel coordinates in the two original `Pic`s, `combine` calls the given function to compute the color of the corresponding pixel in the new `Pic`. The new `Pic`’s width equals the lesser of the two originals’ widths; the same goes for height.

## Parameters

determinePixel

  a function generates a pixel for the combination, given two pixel colors from the same location in the originals

## Attributes

Returns

  the new (bitmap) image obtained by calling `determinePixel` and putting together the outputs

def contains(pixel: Pos): Boolean

Determines if the given Pos is within this `Pic`’s borders. For that to be the case, the `Pos` object’s `x` needs to be between zero (inclusive) and this `Pic`’s `width` (exclusive) and its `y` needs to be between zero (inclusive) and this `Pic`’s `height` (exclusive).

Determines if the given Pos is within this `Pic`’s borders. For that to be the case, the `Pos` object’s `x` needs to be between zero (inclusive) and this `Pic`’s `width` (exclusive) and its `y` needs to be between zero (inclusive) and this `Pic`’s `height` (exclusive).

## Attributes

def counterclockwise(degrees: Double): Pic

Creates version of this `Pic` that’s rotated counterclockwise around its center. The resulting image is sized so that the entire contents of the original `Pic` are visible; any empty space in the corners is Transparent.

Creates version of this `Pic` that’s rotated counterclockwise around its center. The resulting image is sized so that the entire contents of the original `Pic` are visible; any empty space in the corners is Transparent.

## Parameters

degrees

  the amount of counterclockwise rotation, in degrees; if unspecified, defaults to 90.0

## Attributes

Returns

  a new `Pic` that is a rotated version of this one; it will usually be a bitmap, but some simple vector-based `Pic`s may retain their vector form

def crop(boundary: Bounds): Pic

Returns a partial `Pic` of a rectangular area within this `Pic`.

Returns a partial `Pic` of a rectangular area within this `Pic`.

## Parameters

boundary

  the cropping frame within this `Pic`

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a part of the original

def crop(topLeft: Pos, bottomRight: Pos): Pic

Returns a partial `Pic` of a rectangular area within this `Pic`.

Returns a partial `Pic` of a rectangular area within this `Pic`.

## Parameters

bottomRight

  the cropping frame’s bottom-right corner within this `Pic`; this point must not be out side the `Pic`

topLeft

  the cropping frame’s top-left corner within this `Pic`; this point must not be outside the `Pic`

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a part of the original

def crop(topLeft: Pos, width: Double, height: Double): Pic

Returns a partial `Pic` of a rectangular area within this `Pic`.

Returns a partial `Pic` of a rectangular area within this `Pic`.

## Parameters

height

  the height of the cropping frame

topLeft

  the cropping frame’s top-left corner within this `Pic`

width

  the width of the cropping frame

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a part of the original

def crop(x: Double, y: Double, width: Double, height: Double): Pic

Returns a partial `Pic` of a rectangular area within this `Pic`.

Returns a partial `Pic` of a rectangular area within this `Pic`.

## Parameters

height

  the height of the cropping frame

width

  the width of the cropping frame

x

  the x coordinate of the cropping frame’s left edge within this `Pic`

y

  the y coordinate of the cropping frame’s top edge within this `Pic`

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a part of the original

def flipDiagonal: Pic

Creates mirrored version of this `Pic`: what’s in each corner of the original is in the opposite corner of the resulting `Pic`.

Creates mirrored version of this `Pic`: what’s in each corner of the original is in the opposite corner of the resulting `Pic`.

## Attributes

Returns

  a new `Pic` (a bitmap) that is a flipped version of this one

def flipHorizontal: Pic

Creates mirrored version of this `Pic`: what’s on the left in the original is on the right in the resulting `Pic` and vice versa.

Creates mirrored version of this `Pic`: what’s on the left in the original is on the right in the resulting `Pic` and vice versa.

## Attributes

Returns

  a new `Pic` (a bitmap) that is a flipped version of this one

def flipVertical: Pic

Creates mirrored version of this `Pic`: what’s at the top in the original is at the bottom in the resulting `Pic` and vice versa.

Creates mirrored version of this `Pic`: what’s at the top in the original is at the bottom in the resulting `Pic` and vice versa.

## Attributes

Returns

  a new `Pic` (a bitmap) that is a flipped version of this one

def freeze: Pic

Forces rasterization of any vector graphics in this `Pic`’s internal representation into bitmap form. See the introduction to this class for more information.

Forces rasterization of any vector graphics in this `Pic`’s internal representation into bitmap form. See the introduction to this class for more information.

## Attributes

Returns

  the same picture, stored entirely in bitmap form

See also

  isBitmap

def hide(): Unit

Hides the window that has been created (with show) to display the `Pic`. If there is no such window, does nothing.

Hides the window that has been created (with show) to display the `Pic`. If there is no such window, does nothing.

Students may alternatively use the `hide(pic)` variant in the top-level package o1.

## Attributes

See also

  show, Pic.hide

def isBitmap: Boolean

Indicates whether this `Pic` is internally stored as a bitmap raster. See the introduction to this class for more information.

Indicates whether this `Pic` is internally stored as a bitmap raster. See the introduction to this class for more information.

## Attributes

Returns

  `true` if the entire `Pic` is rasterized as a bitmap; `false` if the `Pic`’s internal representation uses any vector graphics

See also

  freeze

infix def leftOf(rightPic: Pic, retainAnchor: Boolean): Pic

Combines this `Pic` and the given one so that this `Pic` appears immediately to the left the other `Pic`. The combined `Pic` will be large enough to fit both originals.

Combines this `Pic` and the given one so that this `Pic` appears immediately to the left the other `Pic`. The combined `Pic` will be large enough to fit both originals.

## Parameters

retainAnchor

  `true` means that the anchor of the combination should be equally far from the top left-hand corner as this `Pic`’s anchor is; `false` (the default) means that the combination should follow the same general anchoring policy has this `Pic` (e.g., to anchor from its center). If unspecified, defaults to `false`.

rightPic

  the `Pic` that is to the right of this `Pic` in the combination

## Attributes

Returns

  the combined `Pic`

See also

  above, below, rightOf, rowOf

def onto(backPic: Pic, my: Anchor, atIts: Anchor): Pic

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic`. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` uses the given Anchors instead of the default `anchor` of either of the original `Pic`s.

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic`. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` uses the given Anchors instead of the default `anchor` of either of the original `Pic`s.

## Parameters

atIts

  the point within `backPic` that this `Pic` is positioned at

backPic

  the `Pic` that is behind this one in the combination

my

  the point within this `Pic` that will be placed at `atIts`

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but leaves out any “hanging” parts of the foreground image

infix def onto(backPic: Pic, atIts: Anchor): Pic

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic`. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` anchors this `Pic` from its default anchor to an anchor in the other image.

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic`. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` anchors this `Pic` from its default anchor to an anchor in the other image.

## Parameters

atIts

  the point within `backPic` that this `Pic`’s anchor is positioned at; if unspecified, defaults to Center

backPic

  the `Pic` that is behind this one in the combination

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but leaves out any “hanging” parts of the foreground image

def onto(backPic: Pic, at: Pos): Pic

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic` at specific coordinates. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` anchors this `Pic` at its default anchor.

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic` at specific coordinates. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` anchors this `Pic` at its default anchor.

## Parameters

at

  the point within `backPic` that this `Pic`’s anchor is positioned at

backPic

  the `Pic` that is behind this one in the combination

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but leaves out any “hanging” parts of the foreground image

def onto(backPic: Pic, my: Anchor, at: Pos): Pic

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic` at specific coordinates. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` uses the given Anchor instead of this `Pic`s default `anchor`.

Combines this `Pic` and the given one so that this `Pic` appears in front of the other `Pic` at specific coordinates. The combined `Pic` will be larger than either of the two originals unless this `Pic` fits completely in front of the other one. This version of `onto` uses the given Anchor instead of this `Pic`s default `anchor`.

## Parameters

at

  the point within `backPic` that this `Pic` is positioned at

backPic

  the `Pic` that is behind this one in the combination

my

  the point within this `Pic` that will be placed at the given coordinates

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but leaves out any “hanging” parts of the foreground image

def pixelColor(pos: Pos): Color

Returns the color of the pixel at the given position within the image.

Returns the color of the pixel at the given position within the image.

The given position must be within the image’s bounds; an out-of-bounds error will occur otherwise.

N.B. This is inefficient on a `Pic` that’s not fully rasterized as a bitmap. If you have a vector graphic and need to call this method many times, consider freezing the `Pic` first.

## Attributes

def pixelColor(x: Int, y: Int): Color

Returns the color of the pixel at the given coordinates within the image.

Returns the color of the pixel at the given coordinates within the image.

The given position must be within the image’s bounds; an out-of-bounds error will occur otherwise.

N.B. This is inefficient on a `Pic` that’s not fully rasterized as a bitmap. If you have a vector graphic and need to call this method many times, consider freezing the `Pic` first.

## Attributes

def pixelColor(x: Double, y: Double): Color

Returns the color of the pixel at the given coordinates within the image.

Returns the color of the pixel at the given coordinates within the image.

The given position must be within the image’s bounds; an out-of-bounds error will occur otherwise.

N.B. This is inefficient on a `Pic` that’s not fully rasterized as a bitmap. If you have a vector graphic and need to call this method many times, consider freezing the `Pic` first.

## Attributes

def pixelsNear(pos: Pos, range: Double): Seq[Color]

Returns the colors of the pixels in this `Pic` that are “near” a given Pos. A pixel counts as being near if it’s located at a `Pos` whose distance from the given `Pos` is less than or equal to the given `range`. This includes the pixel at the given `Pos` (if there is one). Distances are measured from the “center” of each pixel; for example, if pixel A is two pixels right and three pixels down pixel B, then their distance is five.

Returns the colors of the pixels in this `Pic` that are “near” a given Pos. A pixel counts as being near if it’s located at a `Pos` whose distance from the given `Pos` is less than or equal to the given `range`. This includes the pixel at the given `Pos` (if there is one). Distances are measured from the “center” of each pixel; for example, if pixel A is two pixels right and three pixels down pixel B, then their distance is five.

## Parameters

pos

  a position whose nearby pixels in this `Pic` will be returned

range

  the maximum distance of a returned pixel from `pos` (must be non-negative)

## Attributes

Returns

  a collection of the pixel colors, in arbitrary order

def place(foreground: Pic, its: Anchor, at: Pos): Pic

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` uses the given Anchor instead of the other `Pic`s default `anchor` and places it at a specific Pos in this background.

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` uses the given Anchor instead of the other `Pic`s default `anchor` and places it at a specific Pos in this background.

## Parameters

at

  the point within this `Pic` that `foreground` will be placed at

foreground

  the `Pic` that will be placed against this background

its

  the point within `foreground` that will be placed at the given coordinates

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but switches the order of the two `Pic`s

def place(foreground: Pic, its: Anchor, atMy: Anchor): Pic

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` uses the given Anchors instead of the default `anchor` of either of the original `Pic`s.

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` uses the given Anchors instead of the default `anchor` of either of the original `Pic`s.

## Parameters

atMy

  the point within this `Pic` that `foreground` will be placed at

foreground

  the `Pic` that will be placed against this background

its

  the point within `foreground` that will be placed at the given coordinates

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but switches the order of the two `Pic`s

def place(foreground: Pic, at: Pos): Pic

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` anchors the other `Pic` at its default anchor to a specific Pos in this background.

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` anchors the other `Pic` at its default anchor to a specific Pos in this background.

## Parameters

at

  the point within this `Pic` that `foreground`’s anchor will be placed at

foreground

  the `Pic` that will be placed against this background

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but switches the order of the two `Pic`s

def place(foreground: Pic, atMy: Anchor): Pic

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` anchors the other `Pic` at its default anchor to a specified anchor in this background.

Combines this `Pic` and the given one so that this `Pic` serves as a background and the other `Pic` appears in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. Some or even none of the other `Pic` is visible in front of this background, depending on the relative positioning and dimensions of the two images; any parts of the other `Pic` that don’t fit against this background are left out. (The left-out parts are still part of this `Pic`’s data but not visible; only the part within this framing background image will be shown when the `Pic` is rendered onscreen.) This version of `place` anchors the other `Pic` at its default anchor to a specified anchor in this background.

## Parameters

atMy

  the point within this `Pic` that `foreground`’s anchor will be placed at

foreground

  the Pic` that will be placed against this background

## Attributes

Returns

  the combined `Pic`

See also

  `against`, which does the same but switches the order of the two `Pic`s

def place(foregroundPics: Iterable[(Pic, Pos)]): Pic

Combines this `Pic` and the given ones so that this `Pic` serves as a background and the other `Pic`s appear in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. This is equivalent to calling `place(Pic,Pos)` repeatedly.

Combines this `Pic` and the given ones so that this `Pic` serves as a background and the other `Pic`s appear in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. This is equivalent to calling `place(Pic,Pos)` repeatedly.

## Parameters

foregroundPics

  tuples containing: the `Pic`s that will be placed against this background and the points within this `Pic` where their default anchors will be placed

## Attributes

Returns

  the combined `Pic`

def place(foregroundPics: (Pic, Pos)*): Pic

Combines this `Pic` and the given ones so that this `Pic` serves as a background and the other `Pic`s appear in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. This is equivalent to calling `place(Pic,Pos)` repeatedly.

Combines this `Pic` and the given ones so that this `Pic` serves as a background and the other `Pic`s appear in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. This is equivalent to calling `place(Pic,Pos)` repeatedly.

## Parameters

foregroundPics

  tuples containing: the `Pic`s that will be placed against this background and the points within this `Pic` where their default anchors will be placed

## Attributes

Returns

  the combined `Pic`

inline def placeCopies(foregroundPic: Pic, at: Iterable[Pos]): Pic

Combines this `Pic` and copies of the given one so that this `Pic` serves as a background and the copies of the other `Pic`s appear in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. This is equivalent to calling `place(Pic,Pos)` repeatedly, passing in the same foreground image each time.

Combines this `Pic` and copies of the given one so that this `Pic` serves as a background and the copies of the other `Pic`s appear in front but not beyond this `Pic`’s borders. The visible part of the combined `Pic` is the size of this background `Pic`. This is equivalent to calling `place(Pic,Pos)` repeatedly, passing in the same foreground image each time.

## Parameters

at

  the points within this `Pic` where the default anchors of the copies should be placed

foregroundPic

  the `Pic`s whose copies will be placed against this background

## Attributes

Returns

  the combined `Pic`

infix def rightOf(leftPic: Pic, retainAnchor: Boolean): Pic

Combines this `Pic` and the given one so that this `Pic` appears immediately to the right the other `Pic`. The combined `Pic` will be large enough to fit both originals.

Combines this `Pic` and the given one so that this `Pic` appears immediately to the right the other `Pic`. The combined `Pic` will be large enough to fit both originals.

## Parameters

leftPic

  the `Pic` that is to the left of this `Pic` in the combination

retainAnchor

  `true` means that the anchor of the combination should be equally far from the top left-hand corner as this `Pic`’s anchor is; `false` (the default) means that the combination should follow the same general anchoring policy has this `Pic` (e.g., to anchor from its center). If unspecified, defaults to `false`.

## Attributes

Returns

  the combined `Pic`

See also

  above, below, leftOf, rowOf

def rowOf(number: Int): Pic

Combines copies of this `Pic` so that they appear in a horizontal row. The combined `Pic` will be large enough to fit all the copies.

Combines copies of this `Pic` so that they appear in a horizontal row. The combined `Pic` will be large enough to fit all the copies.

## Parameters

number

  the number of copies in the row (e.g., 3 means the result has three identical images)

## Attributes

See also

  leftOf, rightOf, columnOf, alternatingRow

def save(path: String): Boolean

Saves the `Pic` in the given file in PNG format.

Saves the `Pic` in the given file in PNG format.

## Parameters

path

  an absolute local path or a path relative to the working directory

## Attributes

Returns

  `true` if the saving was successful and `false` if no file was created because there was no bitmap to save

def scaleBy(factor: Double): Pic

Creates a version of this `Pic` that is larger or smaller as per the given multiplier. A value between 0 and 1 produces a smaller `Pic`, a value above 1 a larger one. Retains the aspect ratio of the original image.

Creates a version of this `Pic` that is larger or smaller as per the given multiplier. A value between 0 and 1 produces a smaller `Pic`, a value above 1 a larger one. Retains the aspect ratio of the original image.

## Parameters

factor

  the ratio between the sizes of the result and the original

## Attributes

Returns

  a new `Pic` that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based `Pic`s may retain their vector form

def scaleTo(targetWidth: Double, targetHeight: Double): Pic

Creates a scaled version of this `Pic` that has the given dimensions. The aspect ratio of the resulting image may be different from the original’s.

Creates a scaled version of this `Pic` that has the given dimensions. The aspect ratio of the resulting image may be different from the original’s.

## Parameters

targetHeight

  the height of the output image

targetWidth

  the width of the output image

## Attributes

Returns

  a new `Pic` that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based `Pic`s may retain their vector form

def scaleTo(targetSize: Double): Pic

Creates a scaled version of this `Pic` that has the given size and is rectangular. If the original `Pic` isn’t rectangular, the aspect ratio of the result will be different.

Creates a scaled version of this `Pic` that has the given size and is rectangular. If the original `Pic` isn’t rectangular, the aspect ratio of the result will be different.

## Parameters

targetSize

  the width and height of the output image

## Attributes

Returns

  a new `Pic` that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based `Pic`s may retain their vector form

def scaleTo(sizingPic: Pic): Pic

Creates a scaled version of this `Pic` that has the dimensions of the given `Pic`. The aspect ratio of the resulting image may be different from the original’s.

Creates a scaled version of this `Pic` that has the dimensions of the given `Pic`. The aspect ratio of the resulting image may be different from the original’s.

## Parameters

sizingPic

  a `Pic` whose width and height are given to the scaled `Pic`

## Attributes

Returns

  a new `Pic` that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based `Pic`s may retain their vector form

def shiftDown(offset: Double): Pic

Shifts each pixel within the `Pic` downwards by the given amount. Retains the size of the image: any pixels that would go beyond the bottom edge of the `Pic` instead wrap around to the top.

Shifts each pixel within the `Pic` downwards by the given amount. Retains the size of the image: any pixels that would go beyond the bottom edge of the `Pic` instead wrap around to the top.

## Parameters

offset

  the number of pixels the image shifts down

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a shifted version of the original

def shiftLeft(offset: Double): Pic

Shifts each pixel within the `Pic` to the left by the given amount. Retains the size of the image: any pixels that would go beyond the left edge of the `Pic` instead wrap around to the right-hand side.

Shifts each pixel within the `Pic` to the left by the given amount. Retains the size of the image: any pixels that would go beyond the left edge of the `Pic` instead wrap around to the right-hand side.

## Parameters

offset

  the number of pixels the image shifts to the left

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a shifted version of the original

def shiftRight(offset: Double): Pic

Shifts each pixel within the `Pic` to the right by the given amount. Retains the size of the image: any pixels that would go beyond the right edge of the `Pic` instead wrap around to the left-hand side.

Shifts each pixel within the `Pic` to the right by the given amount. Retains the size of the image: any pixels that would go beyond the right edge of the `Pic` instead wrap around to the left-hand side.

## Parameters

offset

  the number of pixels the image shifts to the right

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a shifted version of the original

def shiftUp(offset: Double): Pic

Shifts each pixel within the `Pic` upwards by the given amount. Retains the size of the image: any pixels that would go beyond the top edge of the `Pic` instead wrap around to the bottom.

Shifts each pixel within the `Pic` upwards by the given amount. Retains the size of the image: any pixels that would go beyond the top edge of the `Pic` instead wrap around to the bottom.

## Parameters

offset

  the number of pixels the image shifts up

## Attributes

Returns

  a new `Pic` (a bitmap) that contains a shifted version of the original

def show(background: Color, border: Int): Unit

Displays this `Pic` in a minimalistic GUI window. Calling this method repeatedly on the same `Pic` doesn’t display multiple windows but reuses the existing one. This method is meant only for experimentation and debugging; not for GUI construction (cf. views).

Displays this `Pic` in a minimalistic GUI window. Calling this method repeatedly on the same `Pic` doesn’t display multiple windows but reuses the existing one. This method is meant only for experimentation and debugging; not for GUI construction (cf. views).

Students may alternatively use the `show(pic)` variant in the top-level package o1.

## Parameters

background

  the color to appear behind the `Pic` in the frame (where the `Pic` is transparent); defaults to a light gray (`White70`)

border

  the width of the simple black window frame, in pixels; if unspecified, defaults to 1

## Attributes

See also

  hide

  Pic.show

override def toString: String

Returns a very simple string description of this `Pic`. Examples:

Returns a very simple string description of this `Pic`. Examples:

- `"ladybug.png"`
- `circle-shape`
- `"ladybug.png" (transformed)`
- `circle-shape (transformed)`
- `combined pic`

## Attributes

Definition Classes
  Any

def transformColors(transformer: Color => Color): Pic

Applies the given operation to each pixel in the `Pic` to generate a different `Pic`. That is, every color in the image will be replaced by another color in the generated image, as specified by the given function.

Applies the given operation to each pixel in the `Pic` to generate a different `Pic`. That is, every color in the image will be replaced by another color in the generated image, as specified by the given function.

## Parameters

transformer

  a function that `transformColors` calls on every pixel in the image to map its color to a new one

## Attributes

Returns

  the new (bitmap) image obtained by calling `transformer` and putting together the outputs

def transformXY(newColorAt: (Int, Int) => Color): Pic

Applies the given operation to each position in the `Pic` to generate a different `Pic`.

Applies the given operation to each position in the `Pic` to generate a different `Pic`.

## Parameters

newColorAt

  a function that `transformXY` calls repeatedly to determine the pixels of the transformed `Pic`

## Attributes

Returns

  the new (bitmap) image obtained by calling `newColorAt` and putting together the outputs

def withHistoryLength(maxLength: Int): Pic

Sets a new limit to the history length on the `Pic`.

Sets a new limit to the history length on the `Pic`.

## Parameters

maxLength

  a new historyLength (>= 0)

## Attributes

#### Inherited methods

def centerFromTopLeft: Pos

the location of this object’s center: the average point between its edges, expressed in coordinates relative to the object’s top left-hand corner

the location of this object’s center: the average point between its edges, expressed in coordinates relative to the object’s top left-hand corner

## Attributes

Inherited from:
  HasSize

def internalAnchorPos: Pos

Returns the Pos of the anchoring point within this object, expressed as coordinates relative to the object’s top left-hand corner.

Returns the Pos of the anchoring point within this object, expressed as coordinates relative to the object’s top left-hand corner.

## Attributes

Inherited from:
  HasAnchor

def internalAnchorX: Double

Returns the x coordinate of the anchoring point within this object, relative to the object’s left edge.

Returns the x coordinate of the anchoring point within this object, relative to the object’s left edge.

## Attributes

Inherited from:
  HasAnchor

def internalAnchorY: Double

Returns the y coordinate of the anchoring point within this object, relative to the object’s top edge.

Returns the y coordinate of the anchoring point within this object, relative to the object’s top edge.

## Attributes

Inherited from:
  HasAnchor

#### Concrete fields

val anchor: Anchor

The `Pic`’s anchor.

The `Pic`’s anchor.

## Attributes

lazy val dimensions: (Double, Double)

The width and height of the `Pic` as a tuple.

The width and height of the `Pic` as a tuple.

## Attributes

lazy val height: Double

The height of the `Pic` in pixels.

The height of the `Pic` in pixels.

## Attributes

lazy val history: List[String]

A list of method names used for creating this `Pic`. Only the most recently applied methods are listed (up to historyLength. This method may be useful for demonstrative purposes, debugging, and/or automatic assessment.

A list of method names used for creating this `Pic`. Only the most recently applied methods are listed (up to historyLength. This method may be useful for demonstrative purposes, debugging, and/or automatic assessment.

## Attributes

val historyLength: Int

A limit on the number of historical method calls that are tracked by the `Pic` and available through history. Defaults to 10. Can be changed via withHistoryLength.

A limit on the number of historical method calls that are tracked by the `Pic` and available through history. Defaults to 10. Can be changed via withHistoryLength.

## Attributes

lazy val toIcon: Option[Icon]

This `Pic` converted to a Swing `Icon`.

This `Pic` converted to a Swing `Icon`.

## Attributes

lazy val toImage: Option[BufferedImage]

This `Pic` converted to a Java AWT `BufferedImage` (for use in Swing GUIs).

This `Pic` converted to a Java AWT `BufferedImage` (for use in Swing GUIs).

## Attributes

lazy val width: Double

The width of the `Pic` in pixels.

The width of the `Pic` in pixels.

## Attributes