This changes the API of this function. The correct way to go about this is to deprecate this one and have a new function set up to replace it. Or, have a kwarg defaulting to False to indicate whether to return the codes as well.

@WeatherGod: I have changed all code that calls this and the other function you have highlighted. I see these as internal (i.e. private) functions, even though they are do not have leading underscores.

They are not private. These are public methods to objects that people do manipulate in the wild. You will have to go through the proper process for this change.

Same thing here. Can't change the output API without some sort of transition period.

I am not quite understanding why this is needed, though. Doesn't the Polygons in the PolyCollection have their own codes?

@WeatherGod, you need to understand the existing code for my changes to make sense. Take a look at the Poly3DCollection class in art3d.py, which is derived from the 2D PolyCollection in collections.py. Poly3DCollection stores the 3D vertices in self._vec and self._segis. Each time Poly3DCollection.do_3d_projection is called, the 3D vertices are transformed and projected into 2D points that are stored in the usual PolyCollection._paths that are used for rendering.

The root cause of issue #178 is that a 2D PolyCollection has both 2D vertices and 2D codes. The codes are used so that single arrays of vertices and codes can be used for multiple polygons, such as when a contour needs to render a hole polygon inside another polygon. Up until now, Poly3DCollection has had no understanding of these codes and so has rendered all the vertices as though they were a single polygon, causing incorrect rendering.

My solution to this is to follow the existing (IMHO poor) implementation, and store the codes in Poly3DCollection as self._codes3d much like the vertices are stored as self._vec and self._segis. Each time do_3d_projection is called, both the stored vertices and codes are transformed/projected and used to update the PolyCollection._paths that are used for rendering.

As an aside, the Poly3DCollection constructor is never called for 3D contours, instead the function poly_collection_2d_to_3d does some very nasty object creation without calling the constructor. I believe this is to avoid the base PolyCollection constructor being called, as this will complain that the vertices are not 2D. I put the line you have asked about in the constructor because it should be initialised whenever the constructor is called, but of course that argument also applies to self._vec and self._segis but this has not been done before for some reason.

As I said at the top of the PR, my code changes are not elegant but they are consistent (i.e. no worse than) the existing code. I didn't really want to touch any of the mplot3d code, but as you said you didn't know how to solve the problem I thought I'd give it a try.

Ok, I see it now. A 3d polygon with a hole would need a MOVETO, but that information is never really conveyed properly.

As for your aside, you are absolutely right. I am the third maintainer of this codebase, and there is a lot of stuff in it that has been "don't touch because it might break". The reason for the oddity in the object creation is probably one borne of "getting the job done". The idea for most of these things is to let the 2D plotting functions do their jobs, and then augment them with the third dimension information.

@WeatherGod: You are correct, I have not explained the fix in the code but pretty much nothing is explained in the existing mplot3d code. As I keep saying, my changes are consistent with the existing code.

The more I think about it the less I want my name associated with the mplot3d codebase, hence I am closing this PR. I have diagnosed the problem and come up with a fix, albeit possibly a poor fix, so you or someone else can use my code as the basis for an acceptable fix if you wish.

You still owe me a pint as for figuring about the bug as you promised in #1299!