Opened 11 years ago

Closed 11 years ago

#4043 closed enhancement (fixed)

Improve gdalwarp -cutline documentation page

Reported by: EliL Owned by: warmerdam
Priority: normal Milestone:
Component: Docs Version: unspecified
Severity: trivial Keywords: gdalwarp, cutline, documentation
Cc: eadam@…

Description (last modified by EliL)

Right now that gdalwarp cutline documentation says:

-cutline datasource:

Enable use of a blend cutline from the name OGR support datasource.

Even spend some considerable effort to help me understand it (Thanks). What I failed to understand was that it was the application of a mask, not altering the original raster. I would like to suggest the documentation be changed to:

-cutline datasource:

Enable use of a blend cutline from the named OGR supported datasource. This applies a mask to the raster without altering the original raster.

Perhaps even a direct suggestion to also use -crop_to_cutline or -te if you want to actually get rid of the data that you are masking. Usually the docs are appropriately concise without excess chatter so perhaps not.

I ran across this by applying -cutline to a small portion of a 3G raster and got back a 3G raster. That was not what I expected. I did eventually figure out to use -crop_to_cutline but was then confused as to exactly what -cutline was doing (namely preserving the data).

Thinking about this more, perhaps the -crop_to_cutline docs should change too, although this seems less needed. Right now it says,

-crop_to_cutline:

(GDAL >= 1.8.0) Crop the extent of the target dataset to the extent of the cutline.

What do you think of:

-crop_to_cutline:

(GDAL >= 1.8.0) Crop the extent of the target dataset to the extent of the cutline. Not specifying this when using -cutline will keep the full extent and data of the original raster.

Change History (2)

comment:1 by EliL, 11 years ago

Description: modified (diff)

comment:2 by Even Rouault, 11 years ago

Resolution: fixed
Status: newclosed

Taking inspiration from your suggestion, but with some variations:

r22171 /trunk/gdal/apps/gdalwarp.cpp: gdalwarp: improve doc about cutline (#4043)

Note: See TracTickets for help on using tickets.