@wanderingnature I'm sorry that pad/crop are a confusing combination. If it helps, here is the code in question (https://github.com/rasterio/rasterio/blob/main/rasterio/mask.py#L72-L77):

    if crop and pad:
        pad_x = pad_width
        pad_y = pad_width
    else:
        pad_x = 0
        pad_y = 0

The intent is that padding is applied to the input shapes for using when cropping, only. Padding should have no affect if you don't select the cropping option.

@sgillies - thanks for your reply. I tested all the possible cases of crop and pad - they make sense (but a few exceptions which can be reasoned out) given the code as fas as when the params are applied. The interaction of the various params can also be tricky depending on what you are providing as dataset and shape, for instance if you want to pad but the raster doesn't have data there you need to consider how you want those areas handled (fill, nodata). That's all logical though when you think about.

The exceptions that do puzzle me are regarding pad_width values... In this example the raster overlaps the shape considerably, so there is data there for padding.

These two test cases make perfect sense: pad_width=-1 subtracts a pixel from all sides, pad_width=1 adds a nodata pixel on all sides.

This test doesn't make sense - the default pad_width of 0.5 should be used, the output is 130x130 and there is nodata on all sides.

The documentation says : pad_width (float (opt)) – If pad is set (to maintain back-compatibility), then this will be the pixel-size width of the padding around the mask.

Thinking about that - it makes sense that pad_width=0.5 will extend the output by 1 pixel all the way around because 1/2 pixel makes no sense.

These cases are both the same output: 130x130 (makes sense since 0.5 is the default, and given that can't have 1/2 a pixel in a raster)
{'crop': True, 'pad': True}
{'crop': True, 'pad': True, 'pad_width': 0.5}

These cases are both the same output: 128x128 ( makes sense regarding the 1/2 pixel and we see that the rounding is always UP)
{'crop': True, 'pad': True, 'pad_width': 0.0},
{'crop': True, 'pad': True, 'pad_width': -0.5},

If you have negative pad_width then the pixel rounding does not need to consider nodata - there's raster data there.

But that's when it gets tricky with the fill parameter, which applies to 'the pixels outside the features'

0.5 the pixels are outside the feature - they get filled with nodata
-0.5 the pixels are inside the feature - they do not get filled, just the raster data is used

Still not quite sure why the default pad_width is 0.5, maybe that's just to make sure the clipped extends just a little past the boundary to make sure all the data of the raster is collected?

My original findings were not so clear so that's why I made up a test script.For the record here's a plot of all the test cases.