> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2.ard.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Map Drawing Guide
> How to generate map images from ModMS data
ModMS can generate map images (PNG) from weather model data with customizable styling, colormaps, contours, and vector overlays.
## Map Generation Endpoint
**Base URL:** `http://modms.devops.arabiaweather.com/q`
**Format:** Set `format=png` to generate a map image instead of JSON data.
## Required Parameters
### Fields
The `fields` parameter specifies what to plot. For vector data (wind), use `|` to separate magnitude and direction:
```
fields=speed(GFS.ISO200HPA.UGRD, GFS.ISO200HPA.VGRD) | dir(GFS.ISO200HPA.UGRD, GFS.ISO200HPA.VGRD)
```
**Format:**
* **Scalar data**: Single expression (e.g., `GFS.GND2M.TMP-273.15`)
* **Vector data**: Two expressions separated by `|`:
* First: Magnitude (e.g., `speed(u, v)`)
* Second: Direction (e.g., `dir(u, v)`)
**Model Run Specification:**
* **ModMS**: Can use `MODEL.LEVEL.VARIABLE` (latest) or `MODEL@model-run.LEVEL.VARIABLE` (e.g., `GFS@2218`)
* **MAMS**: Must use `MODEL@timestamp.LEVEL.VARIABLE` (e.g., `GFS@1766577600`)
When querying MAMS, you must use timestamp format (`MODEL@timestamp`) instead of model-run format.
### Time
Specify the timestamp for the data:
```
time=1766577600
```
**Format:** Unix timestamp
### Location
Specify the geographic bounding box and image size:
```
location=[(lat1,lon1) to (lat2,lon2) size (width,height)]
```
**Format:**
* **Bounding box**: `(lat1,lon1) to (lat2,lon2)` - Southwest to Northeast corners
* **Image size**: `size (width,height)` - Output image dimensions in pixels
**Example:**
```
location=[(40.9799,22.5) to (55.7766,45) size (512,512)]
```
## Style Parameters
### Color Range
**`min`**: Minimum value for color scale (default: `0`)
**`max`**: Maximum value for color scale (default: `100`)
**`step`**: Step size for color bands (default: `1`)
### Fill Style
**`fill`**: How to fill the map
* `gradient` - Smooth color gradient
* `band` - Discrete color bands
* `none` - No fill (contours only)
### Colormap
**`colormap`**: Color scheme name
**Available colormaps:**
* Standard: `jet`, `hsv`, `magma`, `inferno`, `plasma`, `viridis`, `spectral`
* Diverging: `rdylgn`, `rdbu`, `burd`, `piyg`, `prgn`, `rdylbu`, `brbg`, `rdgy`, `puor`
* Sequential: `orrd`, `pubu`, `bupu`, `oranges`, `bugn`, `ylorbr`, `ylgn`, `reds`, `rdpu`, `greens`, `ylgnbu`, `purples`, `gnbu`, `greys`, `ylorrd`, `purd`, `blues`
* Custom: `shaker1`, `shakerwind`, `shakercape`, `shakercape2`
* Meteorological: `temp`, `temp2`, `temp3`, `wind`, `humid`, `cape`, `gph`, `prec`, `bprec`, `bprec2`, `clouds`, `thickness`
### Contours
**`contour`**: Enable contour lines (`true`/`false`, default: `false`)
**`linewidth`**: Contour line width (default: `1`)
**`contour_color`**: Contour line color (default: `black`)
### Vectors
**`vector`**: Vector overlay style
* `none` - No vectors (default)
* `vector` - Arrow vectors
* `barb` - Wind barbs
* `direction` - Direction only
**`vector_density`**: Number of vectors per grid (default: `40`)
### Grid Numbers
**`numgrid`**: Show grid point values (`true`/`false`, default: `false`)
### Image Size
**`image_width`**: Output image width in pixels (default: auto-calculated)
**`fontsize`**: Font size for labels (default: `0` = auto)
### Saturation
**`saturate_min`**: Saturate values below minimum (`true`/`false`, default: `false`)
**`saturate_max`**: Saturate values above maximum (`true`/`false`, default: `false`)
## Example Requests
### Temperature Map
```bash theme={null}
curl "http://modms.devops.arabiaweather.com/q?fields=GFS.GND2M.TMP-273.15&time=1766577600&location=[(40.9799,22.5)%20to%20(55.7766,45)%20size%20(512,512)]&format=png&min=-10&max=50&step=5&fill=gradient&colormap=burd&contour=false&vector=none"
```
**Decoded:**
```
fields=GFS.GND2M.TMP-273.15
time=1766577600
location=[(40.9799,22.5) to (55.7766,45) size (512,512)]
format=png
min=-10
max=50
step=5
fill=gradient
colormap=burd
contour=false
vector=none
```
### Wind Vector Map
```bash theme={null}
curl "http://modms.devops.arabiaweather.com/q?fields=speed(GFS.ISO200HPA.UGRD%2C%20GFS.ISO200HPA.VGRD)%20%7C%20dir(GFS.ISO200HPA.UGRD%2C%20GFS.ISO200HPA.VGRD)&time=1766577600&location=[(40.9799%2C22.5)%20to%20(55.7766%2C45)%20size%20(512%2C512)]&format=png&fontsize=14&min=0&max=100&step=1&fill=gradient&contour=false&vector=vector&colormap=shakerwind&numgrid=false&linewidth=2&saturate_min=false&saturate_max=false"
```
**Decoded:**
```
fields=speed(GFS.ISO200HPA.UGRD, GFS.ISO200HPA.VGRD) | dir(GFS.ISO200HPA.UGRD, GFS.ISO200HPA.VGRD)
time=1766577600
location=[(40.9799,22.5) to (55.7766,45) size (512,512)]
format=png
fontsize=14
min=0
max=100
step=1
fill=gradient
contour=false
vector=vector
colormap=shakerwind
numgrid=false
linewidth=2
saturate_min=false
saturate_max=false
```
### Precipitation with Contours
```bash theme={null}
curl "http://modms.devops.arabiaweather.com/q?fields=GFS.SFC.APCP.HR&time=1766577600&location=[(30,30)%20to%20(40,40)%20size%20(512,512)]&format=png&min=0&max=25&step=1&fill=gradient&contour=true&colormap=jet&linewidth=2"
```
### MAMS Query with Timestamp Format
When querying MAMS, use timestamp format for model runs:
```bash theme={null}
curl "http://mams.devops.arabiaweather.com:8081/q?fields=speed(GFS%401766577600.ISO200HPA.UGRD%2C%20GFS%401766577600.ISO200HPA.VGRD)%20%7C%20dir(GFS%401766577600.ISO200HPA.UGRD%2C%20GFS%401766577600.ISO200HPA.VGRD)&time=1766577600&location=[(40.9799%2C0)%20to%20(55.7766%2C22.5)%20size%20(512%2C512)]&format=png&fontsize=14&min=0&max=100&step=1&fill=gradient&contour=false&vector=vector&colormap=shakerwind&numgrid=false&linewidth=2&saturate_min=false&saturate_max=false&image_width=512"
```
**Decoded:**
```
fields=speed(GFS@1766577600.ISO200HPA.UGRD, GFS@1766577600.ISO200HPA.VGRD) | dir(GFS@1766577600.ISO200HPA.UGRD, GFS@1766577600.ISO200HPA.VGRD)
time=1766577600
location=[(40.9799,0) to (55.7766,22.5) size (512,512)]
format=png
...
```
Notice the `GFS@1766577600` format - MAMS requires Unix timestamp format, not model-run format like `GFS@2218`.
For information about Crystal layer definitions, see the [Layer Definitions](/data-ai/legacy-met-tools/crystal/layer-definitions) documentation.
## Vector Data Format
For vector overlays (wind, currents), provide two fields separated by `|`:
1. **Magnitude field**: Speed or magnitude value
2. **Direction field**: Direction in degrees
**Example:**
```
fields=speed(GFS.GND10M.UGRD, GFS.GND10M.VGRD) | dir(GFS.GND10M.UGRD, GFS.GND10M.VGRD)
```
The magnitude determines vector length, direction determines orientation.
## Response Format
When `format=png`, the API returns a PNG image that can be:
* Displayed directly in browsers
* Saved to a file
* Embedded in web pages or reports
## Related Documentation
* [Query Guide](/data-ai/modms/querying) - Query syntax and expressions
* [API Examples](/data-ai/modms/api-examples) - Example queries
* [Crystal](/data-ai/legacy-met-tools/crystal) - Frontend for viewing maps