O1Library Docs/API/o1.gui/Pic

Pic

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 Pics 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 Pics 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 Pics that represent combinations or transformations of existing Pics.

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 Pics. 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 Pics 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:

  • Pics 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 Pics 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 Pics but may retain the vector-based representation in simple cases. These are marked with a single asterisk (*).

  • You can call freeze to force rasterization.

Value parameters:
anchor

the anchor of the image

Companion:
object
trait HasAnchor
trait HasSize
class Object
trait Matchable
class Any

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.

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

Returns:

the combined Pic

See also:
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.

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.

Value 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

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 Pics

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 Pics 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 Pics default anchor and places it at a specific Pos in the background.

Value 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

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 Pics

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

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

Value 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

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 Pics

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.

Value 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

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 Pics

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.

Value parameters:
number

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

See also:
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.

Value parameters:
number

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

See also:
def anchorAt(anchor: Anchor): Pic

Anchors the Pic at the given position.

Anchors the Pic at the given position.

Value parameters:
anchor

a new anchoring position

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

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.

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

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.

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.

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

Returns:

the combined Pic

See also:
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.

Value parameters:
degrees

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

Returns:

a new Pic that is a rotated version of this one; it will usually be a bitmap, but some simple vector-based Pics 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.

Value parameters:
number

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

See also:
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 Pics, 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 Pics, 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.

Value parameters:
determinePixel

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

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

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.

Value parameters:
degrees

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

Returns:

a new Pic that is a rotated version of this one; it will usually be a bitmap, but some simple vector-based Pics 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.

Value parameters:
boundary

the cropping frame within this Pic

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.

Value parameters:
bottomRight

the cropping frame’s bottom-right corner within this Pic

topLeft

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

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.

Value 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

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.

Value 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

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.

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.

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.

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 Pics internal representation into bitmap form. See the introduction to this class for more information.

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

Returns:

the same picture, stored entirely in bitmap form

See also:
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.

See also:
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.

Returns:

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

See also:
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.

Value 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

Returns:

the combined Pic

See also:
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 Pics.

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

Value 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

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.

Value 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

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.

Value 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

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 Pics 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 Pics default anchor.

Value 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

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.

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.

def pixelColor(x: Int, y: Int): 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.

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.

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.

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.

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

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

Value 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)

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 Pics 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 Pics default anchor and places it at a specific Pos in this background.

Value 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

Returns:

the combined Pic

See also:

against, which does the same but switches the order of the two Pics

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

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

Value 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

Returns:

the combined Pic

See also:

against, which does the same but switches the order of the two Pics

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.

Value 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

Returns:

the combined Pic

See also:

against, which does the same but switches the order of the two Pics

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.

Value 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

Returns:

the combined Pic

See also:

against, which does the same but switches the order of the two Pics

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

Value parameters:
foregroundPics

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

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

Value parameters:
foregroundPics

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

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

Value parameters:
at

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

foregroundPic

the Pics whose copies will be placed against this background

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.

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

Returns:

the combined Pic

See also:
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.

Value parameters:
number

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

See also:
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.

Value parameters:
path

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

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.

Value parameters:
factor

the ratio between the sizes of the result and the original

Returns:

a new Pic that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based Pics 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.

Value parameters:
targetHeight

the height of the output image

targetWidth

the width of the output image

Returns:

a new Pic that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based Pics 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.

Value parameters:
targetSize

the width and height of the output image

Returns:

a new Pic that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based Pics 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.

Value parameters:
sizingPic

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

Returns:

a new Pic that is a scaled version of this one; it will usually be a bitmap, but some simple vector-based Pics 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.

Value parameters:
offset

the number of pixels the image shifts down

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.

Value parameters:
offset

the number of pixels the image shifts to the left

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.

Value parameters:
offset

the number of pixels the image shifts to the right

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.

Value parameters:
offset

the number of pixels the image shifts up

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.

Value parameters:
background

the color to appear behind the Pic in the frame (where the Pic is transparent)

border

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

See also:
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
Definition Classes
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.

Value parameters:
transformer

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

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.

Value parameters:
newColorAt

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

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.

Value parameters:
maxLength

a new historyLength (>= 0)

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

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.

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.

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.

Inherited from:
HasAnchor

Concrete fields

val anchor: Anchor

the object’s anchoring point

the object’s anchoring point

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.

lazy val height: Double

The height of the Pic in pixels.

The height of the Pic in pixels.

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.

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.

lazy val toIcon: Option[Icon]

This Pic converted to a Swing Icon.

This Pic converted to a Swing Icon.

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

lazy val width: Double

The width of the Pic in pixels.

The width of the Pic in pixels.