pygmt.Figure.image

Figure.image(imagefile, projection=None, box=False, monochrome=False, verbose=False, panel=False, transparency=None, **kwargs)

Plot raster or EPS images.

Reads an Encapsulated PostScript file or a raster image file and plots it on a map. Reads an Encapsulated PostScript (EPS) file or a raster image file and plots it. The image can be scaled arbitrarily, and 1-bit raster images can be

  • inverted, i.e., black pixels (on) becomes white (off) and vice versa

  • colorized, by assigning different foreground and background colors

  • made transparent where one of back- or foreground is painted only.

As an option, the user may choose to convert colored raster images to grayscale using TV’s YIQ-transformation. For raster files, the user can select which color to be made transparent. The user may also choose to replicate the image which, when preceded by appropriate clip paths, may allow larger custom-designed fill patterns to be implemented.

Full GMT docs at https://docs.generic-mapping-tools.org/6.5/image.html.

Aliases:

  • D = position

  • G = bitcolor

  • R = region

  • p = perspective

  • F = box

  • J = projection

  • M = monochrome

  • V = verbose

  • c = panel

  • t = transparency

Parameters:

  • imagefile (str | PathLike) – An Encapsulated PostScript (EPS) file or a raster image file. An EPS file must contain an appropriate BoundingBox. A raster file can have a depth of 1, 8, 24, or 32 bits and is read via GDAL.

  • projection (str) – projcode[projparams/]width|scale. Select map projection.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • position (str) – [g|j|J|n|x]refpoint+rdpi+w[-]width[/height][+jjustify][+nnx[/ny]][+odx[/dy]]. Set reference point on the map for the image.

  • box (Box | bool, default: False) – Draw a background box behind the image. If set to True, a simple rectangular box is drawn using MAP_FRAME_PEN. To customize the box appearance, pass a pygmt.params.Box object to control style, fill, pen, and other box properties.

  • bitcolor (str or list) – [color][+b|f|t]. Change certain pixel values to another color or make them transparent. For 1-bit images you can specify an alternate color for the background (+b) or the foreground (+f) pixels, or give no color to make those pixels transparent. Can be repeated with different settings. Alternatively, for color images you can select a single color that should be made transparent instead (+t).

  • monochrome (bool, default: False) – Convert color image to monochrome grayshades using the (television) YIQ-transformation.

  • verbose (bool or str) – Select verbosity level [Full usage].

  • panel (int | tuple[int, int] | bool, default: False) –

    Select a specific subplot panel. Only allowed when used in Figure.subplot mode.

    • True to advance to the next panel in the selected order.

    • index to specify the index of the desired panel.

    • (row, col) to specify the row and column of the desired panel.

    The panel order is determined by the Figure.subplot method. row, col and index all start at 0.

  • perspective (list or str) – [x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]. Select perspective view and set the azimuth and elevation angle of the viewpoint [Default is [180, 90]]. Full documentation is at https://docs.generic-mapping-tools.org/6.5/gmt.html#perspective-full.

  • transparency (float) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

Examples using pygmt.Figure.image

Image on a figure

Image on a figure