Method add_collection3d

lib/mpl_toolkits/mplot3d/axes3d.py:3073–3142

Add a 3D collection object to the plot. 2D collection types are converted to a 3D version by modifying the object and adding z coordinate information, *zs* and *zdir*. Supported 2D collection types are: - `.PolyCollection` - `.LineCollectio

(self, col, zs=0, zdir='z', autolim=True, *,
                         axlim_clip=False)

        return cset

    def add_collection3d(self, col, zs=0, zdir='z', autolim=True, *,
                         axlim_clip=False):
        """
        Add a 3D collection object to the plot.

        2D collection types are converted to a 3D version by
        modifying the object and adding z coordinate information,
        *zs* and *zdir*.

        Supported 2D collection types are:

        - `.PolyCollection`
        - `.LineCollection`
        - `.PatchCollection` (currently not supporting *autolim*)

        Parameters
        ----------
        col : `.Collection`
            A 2D collection object.
        zs : float or array-like, default: 0
            The z-positions to be used for the 2D objects.
        zdir : {'x', 'y', 'z'}, default: 'z'
            The direction to use for the z-positions.
        autolim : bool, default: True
            Whether to update the data limits.
        axlim_clip : bool, default: False
            Whether to hide the scatter points outside the axes view limits.

            .. versionadded:: 3.10
        """
        had_data = self.has_data()

        zvals = np.atleast_1d(zs)
        zsortval = (np.min(zvals) if zvals.size
                    else 0)  # FIXME: arbitrary default

        # FIXME: use issubclass() (although, then a 3D collection
        #       object would also pass.)  Maybe have a collection3d
        #       abstract class to test for and exclude?
        if type(col) is mcoll.PolyCollection:
            art3d.poly_collection_2d_to_3d(col, zs=zs, zdir=zdir,
                                           axlim_clip=axlim_clip)
            col.set_sort_zpos(zsortval)
        elif type(col) is mcoll.LineCollection:
            art3d.line_collection_2d_to_3d(col, zs=zs, zdir=zdir,
                                           axlim_clip=axlim_clip)
            col.set_sort_zpos(zsortval)
        elif type(col) is mcoll.PatchCollection:
            art3d.patch_collection_2d_to_3d(col, zs=zs, zdir=zdir,
                                            axlim_clip=axlim_clip)
            col.set_sort_zpos(zsortval)

        if autolim:
            if isinstance(col, art3d.Line3DCollection):
                # Handle ragged arrays by extracting coordinates separately
                all_points = np.concatenate(col._segments3d)
                self.auto_scale_xyz(all_points[:, 0], all_points[:, 1],
                                    all_points[:, 2], had_data=had_data)