pygmt.clib.Session.create_data

Session.create_data(family, geometry, mode, dim=None, ranges=None, inc=None, registration='GMT_GRID_NODE_REG', pad=None)[source]

Create an empty GMT data container and allocate space to hold data.

Valid data families and geometries are in FAMILIES and GEOMETRIES.

There are two ways to define the dimensions needed to actually allocate memory:

  1. Via ranges, inc and registration.

  2. Via dim and registration.

    dim contains up to 4 values and they have different meanings for different GMT data families:

    For GMT_DATASET:

    • 0: number of tables

    • 1: number of segments per table

    • 2: number of rows per segment

    • 3: number of columns per row

    For GMT_VECTOR:

    • 0: number of columns

    • 1: number of rows [optional, can be 0 if unknown]

    • 2: data type (e.g., GMT_DOUBLE) [Will be overwritten by put_vector]

    For GMT_GRID/GMT_IMAGE/GMT_CUBE/GMT_MATRIX:

    • 0: number of columns

    • 1: number of rows

    • 2: number of bands or layers [Ignored for GMT_GRID]

    • 3: data type (e.g., GMT_DOUBLE) [For GMT_MATRIX only, but will be overwritten by put_matrix]

    In other words, inc is assumed to be 1.0, and ranges is [0, dim[0], 0, dim[1]] for pixel registration or [0, dim[0]-1.0, 0, dim[1]-1.0] for grid registration.

When creating a grid/image/cube, you can do it in one or two steps:

  1. Call this function with mode="GMT_CONTAINER_AND_DATA". This creates a header and allocates a grid or an image

  2. Call this function twice:

    1. First with mode="GMT_CONTAINER_ONLY", to create a header only and compute the dimensions based on other parameters

    2. Second with mode="GMT_DATA_ONLY", to allocate the grid/image/cube array based on the dimensions already set. This time, you pass NULL for dim/ranges/inc/registration/pad and let data be the void pointer returned in the first step.

    Note: This is not implemented yet, since this function doesn’t have the data parameter.

Parameters:

  • family (str) – A valid GMT data family name (e.g., "GMT_IS_DATASET"). See FAMILIES for valid names.

  • geometry (str) – A valid GMT data geometry name (e.g., "GMT_IS_POINT"). See GEOMETRIES for valid names.

  • mode (str) – A valid GMT data mode. See MODES for valid names. For GMT_IS_DATASET/GMT_IS_MATRIX/GMT_IS_VECTOR, adding GMT_WITH_STRINGS to the mode will allocate the corresponding arrays of string pointers.

  • dim (Sequence[int] | None, default: None) – The dimensions of the dataset, as explained above. If None, will pass in the NULL pointer.

  • ranges (Sequence[float] | None, default: None) – The data extent.

  • inc (Sequence[float] | None, default: None) – The increments between points of the dataset.

  • registration (Literal['GMT_GRID_NODE_REG', 'GMT_GRID_PIXEL_REG'], default: 'GMT_GRID_NODE_REG') – The node registration. Can be "GMT_GRID_PIXEL_REG" or "GMT_GRID_NODE_REG".

  • pad (int | None, default: None) –

    The padding for GMT_IS_GRID/GMT_IS_IMAGE/GMT_IS_CUBE. If None, defaults to "GMT_PAD_DEFAULT".

    For GMT_IS_MATRIX, it can be:

    • 0: default row/col orientation [Default]

    • 1: row-major format (C)

    • 2: column-major format (FORTRAN)

Return type:

c_void_p

Returns:

data_ptr – A ctypes pointer (an integer) to the allocated GMT data container.