Skip to content

r.in.bin

Import a binary raster file into a GRASS raster map layer.

r.in.bin [-fdsbh] input=name output=name [title=phrase] [bytes=integer] [header=integer] [bands=integer] [order=string] [north=float] [south=float] [east=float] [west=float] [rows=integer] [cols=integer] [anull=float] [flip=string [,string,...]] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.in.bin input=name output=name

grass.script.run_command("r.in.bin", input, output, title=None, bytes=None, header=0, bands=1, order="native", north=None, south=None, east=None, west=None, rows=None, cols=None, anull=None, flip=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.in.bin", input="name", output="name")

Parameters

input=name [required]
    Name of binary raster file to be imported
output=name [required]
    Output name or prefix if several bands are imported
title=phrase
    Title for resultant raster map
bytes=integer
    Number of bytes per cell
    Allowed values: 1, 2, 4, 8
header=integer
    Header size in bytes
    Default: 0
bands=integer
    Number of bands in input file
    Bands must be in band-sequential order
    Default: 1
order=string
    Output byte order
    Allowed values: big, little, native, swap
    Default: native
north=float
    Northern limit of geographic region (outer edge)
south=float
    Southern limit of geographic region (outer edge)
east=float
    Eastern limit of geographic region (outer edge)
west=float
    Western limit of geographic region (outer edge)
rows=integer
    Number of rows
cols=integer
    Number of columns
anull=float
    Set Value to NULL
flip=string [,string,...]
    Flip input horizontal and/or vertical
    Allowed values: h, v
    h: Flip input horizontal (East - West)
    v: Flip input vertical (North - South)
-f
    Import as floating-point data (default: integer)
-d
    Import as double-precision floating-point data (default: integer)
-s
    Signed data (two's complement)
-b
    Byte swap the data during import
-h
    Get region info from GMT style header
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Name of binary raster file to be imported
    Used as: input, file, name
output : str, required
    Output name or prefix if several bands are imported
    Used as: output, raster, name
title : str, optional
    Title for resultant raster map
    Used as: phrase
bytes : int, optional
    Number of bytes per cell
    Allowed values: 1, 2, 4, 8
header : int, optional
    Header size in bytes
    Default: 0
bands : int, optional
    Number of bands in input file
    Bands must be in band-sequential order
    Default: 1
order : str, optional
    Output byte order
    Allowed values: big, little, native, swap
    Default: native
north : float, optional
    Northern limit of geographic region (outer edge)
south : float, optional
    Southern limit of geographic region (outer edge)
east : float, optional
    Eastern limit of geographic region (outer edge)
west : float, optional
    Western limit of geographic region (outer edge)
rows : int, optional
    Number of rows
cols : int, optional
    Number of columns
anull : float, optional
    Set Value to NULL
flip : str | list[str], optional
    Flip input horizontal and/or vertical
    Allowed values: h, v
    h: Flip input horizontal (East - West)
    v: Flip input vertical (North - South)
flags : str, optional
    Allowed values: f, d, s, b, h
    f
        Import as floating-point data (default: integer)
    d
        Import as double-precision floating-point data (default: integer)
    s
        Signed data (two's complement)
    b
        Byte swap the data during import
    h
        Get region info from GMT style header
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.in.bin allows the user to create a (binary) GRASS raster map layer from a variety of binary raster data formats.

The -s flag is used for importing two's-complement signed data.

The -h flag is used to read region information from a Generic Mapping Tools (GMT) type binary header. It is compatible with GMT binary grid types 1 and 2.

The north, south, east, and west field values are the coordinates of the edges of the geographic region. The rows and cols values describe the dimensions of the matrix of data to follow. If the input is a GMT binary array (-h flag), the six dimension fields (north, south, east, west, rows and cols) are obtained from the GMT header. If the bytes field is entered incorrectly an error will be generated suggesting a closer bytes value.

r.in.bin can be used to import numerous binary arrays including: ETOPO30, ETOPO-5, ETOPO-2, Globe DEM, BIL, AVHRR and GMT binary arrays (ID 1 & 2).

NOTES

If optional parameters are not supplied, r.in.bin attempts to calculate them. For example if the rows and columns parameters are not entered, r.in.bin automatically calculates them by subtracting south from north and west from east. This will only produce correct results if the raster resolution equals 1. Also, if the north, south, east, and west parameters are not entered, r.in.bin assigns them from the rows and columns parameters. In the AVHRR example (see below), the raster would be assigned a north=128, south=0, east=128, west=0.

The geographic coordinates north, south, east, and west describe the outer edges of the geographic region. They run along the edges of the cells at the edge of the geographic region and not through the center of the cells at the edges.

Eastern limit of geographic region (in projected coordinates must be east of the west parameter value, but in geographical coordinates will wrap around the globe; user errors can be detected by comparing the ewres and nsres values of the imported map layer carefully).
Western limit of geographic region (in projected coordinates must be west of the east parameter value, but in geographical coordinates will wrap around the globe; user errors can be detected by comparing the ewres and nsres values of the imported map layer carefully).

Notes on (non)signed data:

If you use the -s flag, the highest bit is the sign bit. If this is 1, the data is negative, and the data interval is half of the unsigned (not exactly).

This flag is only used if bytes= 1. If bytes is greater than 1, the flag is ignored.

EXAMPLES

GTOPO30 DEM

The following is a sample call of r.in.bin to import GTOPO30 DEM data:

r.in.bin -sb input=E020N90.DEM output=gtopo30 bytes=2 north=90 south=40
east=60 west=20 r=6000 c=4800

(you can add "anull=-9999" if you want sea level to have a NULL value)

GMT

The following is a sample call of r.in.bin to import a GMT type 1 (float) binary array:

r.in.bin -hf input=sample.grd output=sample.grass

(-b could be used to swap bytes if required)

AVHRR

The following is a sample call of r.in.bin to import an AVHRR image:

r.in.bin in=p07_b6.dat out=avhrr c=128 r=128

ETOPO2

The following is a sample call of r.in.bin to import ETOPO2 DEM data (here full data set):

r.in.bin ETOPO2.dos.bin out=ETOPO2min r=5400 c=10800 n=90 s=-90 w=-180 e=180 bytes=2
r.colors ETOPO2min rules=terrain

TOPEX/SRTM30 PLUS

The following is a sample call of r.in.bin to import SRTM30 PLUS data:

r.in.bin -sb input=e020n40.Bathymetry.srtm output=e020n40_topex \
         bytes=2 north=40 south=-10 east=60 west=20 r=6000 c=4800
r.colors e020n40_topex rules=etopo2

GPCP

The following is a sample call of r.in.bin to import GPCP 1DD v1.2 data:

YEAR="2000"
MONTH="01"
# number of days of this month
MDAYS=`date -d"${YEAR}-${MONTH}-01 + 1 month - 1 day" +%d`
r.in.bin in=gpcp_1dd_v1.2_p1d.${YEAR}${MONTH} out=gpcp_${YEAR}.${MONTH}. \
         order=big bytes=4 -f header=1440 anull=-99999 \
         n=90 s=-90 w=0 e=360 rows=180 cols=360 bands=$MDAYS

The following is a sample call of r.in.bin to import GPCP v2.2 data:

r.in.bin in=gpcp_v2.2_psg.1979 out=gpcp_1979. \
         order=big bytes=4 -f header=576 anull=-99999 \
         n=90 s=-90 w=0 e=360 rows=72 cols=144 bands=12

SEE ALSO

r.import, r.out.bin, r.in.ascii, r.out.ascii, r.in.gdal, r.out.gdal, r.in.srtm

AUTHORS

Jacques Bouchard, France (bouchard@onera.fr)
Bob Covill, Canada (bcovill@tekmap.ns.ca)
Markus Metz
Man page: Zsolt Felker (felker@c160.pki.matav.hu)

SOURCE CODE

Available at: r.in.bin source code (history)
Latest change: Friday Feb 07 19:16:09 2025 in commit a82a39f