Tmap ver.3.0 C²

01 / Overview

Overview

Tmap was developed to visualize intermediate calculations and data products from AMATERASS. It reads a headerless Float32 raster and produces a quick-look image with geographic coordinates, a color bar, units, and coastlines.

No external libraries

Tmap compiles and runs with only a standard JDK. It does not depend on a particular operating system or an external graphics library.

Arbitrary grid dimensions

The map, text, color bar, margins, and tick labels are adjusted automatically according to the grid dimensions and aspect ratio.

Coastline cache

Tmap rasterizes the coastline for the requested domain from GSHHG, saves it, and reuses it when the same conditions are requested again.

Float32 gridHeaderless, big-endian, row-major

→

Automatic layoutSize, margins, fonts, and label thinning

→

CoastlineProject GSHHG to the domain and cache it

→

ImageSave as JPEG or PNG

02 / Download & Quick start

Download and quick start

The distribution archive contains the Tmap source code, GSHHG 2.3.7, optional utility programs, and license documents.

Tmap ver.3.0 C² — 2026-08-15d

After extracting the archive, run javac *.java in the Tmap directory.

SHA-256: 7cf7a99b44ca2f111f6efeede875c3670294d6a6d8340d33dd7af9be2a3ee193

Download tar.gz

Extract and compile

tar xzf tmap_v3.0cc_20260815d.tar.gz
cd tmap
javac *.java

Decompress the sample data

bzip2 -d 201605190300.dwn.sw.flx.sfc.fld.4km.bin.bz2

Render the map

java tmap 201605190300.dwn.sw.flx.sfc.fld.4km.bin 1400 0 7 1 auto jpg 60 120 6 85 120 6

Output file: 201605190300.dwn.sw.flx.sfc.fld.4km.bin.jpg
Map domain: 60°N–60°S, 85°E–155°W

1. Download the sample data

Before downloading the data, review the conditions on the Product Download page. The sample is a 4 km Himawari-8 product for 03:00 UTC on 19 May 2016.

Ubuntu

wget -c ftp://amaterass.cr.chiba-u.ac.jp/quasi-realtime/himawari829/archived/FD/201605/20160519/201605190300.dwn.sw.flx.sfc.fld.4km.bin.bz2
bunzip2 201605190300.dwn.sw.flx.sfc.fld.4km.bin.bz2

Fedora

curl -O ftp://amaterass.cr.chiba-u.ac.jp/quasi-realtime/himawari829/archived/FD/201605/20160519/201605190300.dwn.sw.flx.sfc.fld.4km.bin.bz2
bunzip2 201605190300.dwn.sw.flx.sfc.fld.4km.bin.bz2

Windows 10 / 11

curl.exe -O ftp://amaterass.cr.chiba-u.ac.jp/quasi-realtime/himawari829/archived/FD/201605/20160519/201605190300.dwn.sw.flx.sfc.fld.4km.bin.bz2

After downloading, decompress the file with 7-Zip or another program that supports bzip2.

03 / Usage

Usage

For a square raster, Tmap determines the side length automatically from the file size. For a rectangular raster, specify the width and height at the end of the command.

java tmap file max min color_div unit coast_color|auto type north lat_span lat_div west lon_span lon_div [side | width height] [coast_width=auto|1..12]

Argument	Description	Example
file	Input file	`sample.bin`
max / min	Maximum and minimum values of the color scale	`1400 0`
color_div	Number of color-scale intervals	`7`
unit	Reserved number or arbitrary text	`1` or `W/m^2`
coast_color	`auto`, or a gray value from black 0 to white 1	`auto`
type	Output format	`jpg` / `jpeg` / `png`
north / lat_span / lat_div	Northern boundary, latitude span, and number of latitude intervals	`60 120 6`
west / lon_span / lon_div	Western boundary in degrees east, longitude span, and number of longitude intervals	`85 120 6`
side	Side length of a square grid; inferred from the file size when omitted	`3000`
width height	Width and height of a rectangular grid	`3000 1000`
coast_width	Coastline width: `auto` or 1–12 px	`coast_width=3`

Input data

Data type:  IEEE 754 Float32
Byte order: big-endian
Layout:     headerless, row-major

Grid dimensions

For a square raster, Tmap infers the side length from the file size. For a rectangular raster, append width height to the command.

java tmap ... 4500 2000

04 / Adaptive rendering

Arbitrary grid dimensions and aspect ratios

The original version used drawing dimensions tuned for a 3000×3000 grid. Tmap now determines them automatically from the input area, aspect ratio, and measured text widths. It has been tested with grids from 16×16 to 12000×12000 and with both wide and narrow domains.

Examples rendered by Tmap from a 48×16 global grid, a 2250×900 wide grid, and a 600×2250 narrow grid — Upper left: a 48×16 synthetic global grid (60°N–60°S; map body 3:1). Lower left: a 2250×900 wide grid. Right: a 600×2250 narrow grid.

Layout adjustment

Normalize the map by its longer side while preserving the input-grid aspect ratio
Adjust font sizes and line widths according to the rendered area
Measure text with FontMetrics and calculate the required margins
Thin tick labels when necessary to prevent overlap and preserve readability
Retain the original proportions of the color bar, unit label, and margins

Magnification and reduction

Preserve the established sampling rule when reducing a grid
Render every source cell as an evenly allocated rectangle when enlarging a grid
Select coastline colors automatically according to contrast with the background
Determine line width from the output area, with an optional command-line override
Allow the Java heap limit to be specified with -Xmx for large grids

Large rasters: If memory is insufficient, specify the Java heap limit, for example java -Xmx1g tmap ....

05 / Coastline cache

Coastline raster generation and caching

Tmap uses the bundled GSHHG coastline data. Required coastline rasters are created under cache/coastline/ and reused for subsequent maps with the same conditions. If the cache directory is removed, the rasters are generated again as needed.

A newly generated Tmap coastline around Japan for a 500×500 grid — A 500×500 grid covering 48°N–28°N and 130°E–150°E. Tmap selects a suitable GSHHG detail level for the domain and generates a new coastline raster.

First rendering

Tmap checks the geographic domain, grid dimensions, and GSHHG version, then rasterizes the coastline at an appropriate level of detail.

GSHHG → projection → raster mask
                    ↓
          cache/coastline/...

Rendering the same domain again

When a matching cache entry exists, Tmap reads the PNG instead of processing GSHHG again. This keeps coastline processing from becoming a bottleneck when AMATERASS generates many images during its calculations.

cache hit  → read PNG → draw
cache miss → make and save

06 / Units

Unit labels

For W/m² and g/m², the font size and position of the base characters and superscript are controlled independently. In addition to the reserved unit numbers 0 through 10, an arbitrary unit string may be specified.

Number	Display
0	None
1	W/m²
2	μm
3	K
4	km
5	m/s
6	kW/kWp
7	deg
8	hPa
9	g/m²
10	%

A unit not listed above can be supplied directly as text in the unit argument.

07 / History

Development history

Tmap ver.3.0 C² preserves the concise structure and quick-look philosophy of the original program while extending it to arbitrary grid dimensions, aspect ratios, and geographic domains.

2007

Original Tmap

Used to visualize 3000×3000 AMATERASS grids rapidly, inspect intermediate calculations, and generate quick-look images for distribution.

2026

Retains the readable structure and operational philosophy of the original while adding arbitrary grids, automatic layout, global coastline coverage, and caching.

08 / License

License

Separate licenses apply to Tmap itself and to the bundled third-party data. Detailed copyright notices, original license texts, and third-party notices are included in the distribution archive.

Tmap

MIT License

Use, copying, modification, and redistribution are permitted provided that the copyright and license notices are retained.

Bundled coastline data

GSHHG 2.3.7

GNU Lesser General Public License version 3 or later. The distribution includes the GSHHG copyright notice and license documents.