Add a convenience method to rotate a patch

[dmcdougall]

The default behaviour is to rotate the patch about it's centre of mass, otherwise rotate about a specified pivot.

This is to address #987.

I think it'd be better to have this is a convenience method in mlab rather than a new kwarg in the Patch constructor because the patch's transform can't be decided until an Axes object is created.

[pwuertz]

Your parameter is named theta instead of rad.

[dmcdougall]

Thanks! Last minute change I forgot about!

[pelson]

Question to other devs: would you prefer to see this in patches.py?

[WeatherGod]

As a method of patch, it would make sense to have rotation as a property that can be changed at will. Right now, the convenience function is a one-shot deal, which is fine in-of-itself. The problem is that no one is going to be looking in mlab for such a function. Also, what about PatchCollections? Could this be extended to them?

[dmcdougall]

@WeatherGod Good point about mlab. My feeling is that I'm happy to put it in either. If putting in patches.py, would it be a standalone method? So:

import matplotlib.patches as mpatches

...

mpatches.rotate_patch(p, ax, theta)
ax.add_patch(p)

Regarding PatchCollections: can they be disjoint? If so, what should be the default pivot?

[WeatherGod]

If it is going to be a stand-alone function, I would put keep it in mlab for now. I would only want it to be a method of the Patch class itself if one could get/set a rotation value as many times as they like without it adding more rotations to the transform (although I could imagine one wanting a way to apply multiple rotations in series, which your stand-alone function does).

As for the collection, I would think that the desired behavior would be the pivot point is for each patch, rather than the collection as a whole, but I am sure some may think the opposite.

[efiring]

This is half-baked; it seems clear that it doesn't belong in mlab, so I don't think that putting it there "for now" is a good idea. Having it as a stand-alone function in patches seems better, and maybe good enough. But overall, it seems like the best course of action would be to back off, define the problem carefully, and then solve it. The present function might be a good part of the solution--maybe even all of it--but that needs to be clarified.

[wkerzendorf]

Hi guys, I was the original author of the feature request. It would be great if patches.Rectangle had a keyword angle as patches.Ellipse has. This would make many things a lot easier.

[dmcdougall]

Closing this in favour of a new attempt at #1405, implementing @wkerzendorf's suggestion.