Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#7060 closed enhancement (fixed)

Update gdal_rasterize Docs For Creating Raster

Reported by: Jacob Dan Adams Owned by: warmerdam
Priority: low Milestone:
Component: Docs Version: unspecified
Severity: minor Keywords:
Cc:

Description

In my experience, the gdal_rasterize docs at http://www.gdal.org/gdal_rasterize.html are unclear for first-time/infrequent users about when the tool will create a new raster vs modifying (burning-in) an existing raster, and how to interact with the bands when creating a new raster.

Specifically, it was unclear that I should not use -b to reference the bands of a new raster, and that using any of the creation-related options would trigger a new file (instead of updating). It could also be important to warn people that it is possible to unknowingly overwrite an existing raster.

I suggest that lines 1036/1037 of gdal_utilities.dox be modified to reflect the switches that trigger the bCreateOutput flag to True. My attempt at an update is as follows:

Prior to GDAL 1.8.0, gdal_rasterize could only modify existing raster images. Since 1.8.0, it will create a new target raster image when any of the -of, -a_nodata, -init, -a_srs, -co, -te, -tr, -tap, -ts, or -ot options are used. The resolution or size must be specified using the -tr or -ts option for all new rasters. The target raster will be overwritten if it already exists and one of these creation-related options is used.

Further, I suggest that the -b option at lines 1041/1042 be updated to reflect that it is not used for creating new rasters, possibly to this:

The band(s) to burn values into. Multiple -b arguments may be used to burn into a list of bands. The default is to burn into band 1. Not used when creating a new raster.

The dst_filename explanation at lines 1142/1143 could also be modified:

The GDAL supported output file. Must support update mode access. As of GDAL 1.8.0, this file will be created (or overwritten) if the -of, -a_nodata, -init, -a_srs, -co, -te, -tr, -tap, -ts, or -ot options are used.

Finally, I propose a new example demonstrating how to create a new raster, perhaps after line 1165:

The following would burn all polygons from footprint.shp into a new 1000x1000 rgb TIFF as the color red. Note that -b is not used; the order of the -burn options determines the bands of the output raster.

gdal_rasterize -burn 255 -burn 0 -burn 0 -ot Byte -l footprints footprints.shp mask.tif

Attachments (2)

rasterize_dox.txt (2.3 KB ) - added by Jacob Dan Adams 6 years ago.
diff -u of changes to gdal_utilities.dox
gdal_utilities_rasterize.dox (119.2 KB ) - added by Jacob Dan Adams 6 years ago.
Full, modified gdal_utilities.dox

Download all attachments as: .zip

Change History (8)

comment:1 by Even Rouault, 7 years ago

Could you directly edit the file with your changes ?

Download https://svn.osgeo.org/gdal/trunk/gdal/apps/gdal_utilities.dox , make the changes in it, and attach it there (best would be the diff, but if you don't know how to do that, the modified version will do)

comment:2 by warmerdam, 7 years ago

We also used gdal_rasterize recently and I was *trying* to produce a google mercator raster from WGS84 GeoJson input and it was unclear if -a_srs would actually cause things to be reproject properly. It *seemed* something about this process did not work and I'm still not certain what step went wrong. Clarification about automatic reprojection would be desirable.

by Jacob Dan Adams, 6 years ago

Attachment: rasterize_dox.txt added

diff -u of changes to gdal_utilities.dox

by Jacob Dan Adams, 6 years ago

Full, modified gdal_utilities.dox

comment:3 by Jacob Dan Adams, 6 years ago

I've uploaded the output of diff -u as well as the full, modified file. The diff was created using the mingw64 environment on Windows, but the line endings are showing up as Unix-style (LF) and I assume this is what's desired. I can convert the file to different line endings if needed.

Thanks for your patience.

comment:4 by Even Rouault, 6 years ago

Resolution: fixed
Status: newclosed

In 40294:

gdal_rasterize doc: add precisions regarding raster creation (patch by Jacob Dan Adams, fixes #7060)

comment:5 by Even Rouault, 6 years ago

In 40295:

gdal_rasterize doc: make it more clear that -a_srs does not cause reprojection (refs #7060)

in reply to:  2 comment:6 by Even Rouault, 6 years ago

Replying to warmerdam:

We also used gdal_rasterize recently and I was *trying* to produce a google mercator raster from WGS84 GeoJson input and it was unclear if -a_srs would actually cause things to be reproject properly. It *seemed* something about this process did not work and I'm still not certain what step went wrong. Clarification about automatic reprojection would be desirable.

There's indeed some non obvious behaviour in that area:

  • if doing gdal_rasterize in.json existin.tif and out.tif in EPSG:3857, automatic reprojection is done
  • if doing gdal_rasterize in.json new.tif -a_srs EPSG:3857 -ts ... -te ...., reprojection is not done.

The doc of -a_srs says "If incompatible projections between input and output files, no attempt will be made to reproject features.". The "if ...." is probably confusing. The behaviour of -a_srs is that no reprojection is done. I've just clarified this. One might argue that this behaviour is not expected...

Note: See TracTickets for help on using tickets.