pymel.core.modeling.polyGeoSampler

polyGeoSampler(*args, **kwargs)

This command performs a render sampling of surface color and transparency for each selected vertex or face and stores the sampled data as either the color value, or uses the sampled data to displace the affected vertices or faces by a sampled data value. Transparency is not used for displacement, and displacement is performed along vertex normals. The sampled data value used can be pre-scaled by a user defined amount. Additionally, the normals chosen for sampling can be overridden using a “flat” shading option. This option basically means to always use the normals of the faces when computing sampling values. This may be a desired if the user wishes to override an edge smoothness factor. Basically with the “flat” shading option on, edges are always considered to be hard. Note that displacement sampling will result in the -sampleByFace option to be turned off, since a displacement of a vertex always affects the faces the vertex is connected to. Finally, it is possible to force the storage of shared colors per vertex, and / or force the usage of unshared UV values. The computation of the resulting color is as follows: resulting-RGB = (sampled-RGB * scale-factor); if (color blend is none) resulting-RGB = geometry-RGB else if (color blend is add) resulting-RGB = geometry-RGB + sampled-RGB; else if (color blend is subtract) resulting-RGB = geometry-RGB - sampled-RGB; else if (color blend is multiply) resulting-RGB = geometry-RGB * sampled-RGB; else if (color blend is divide) resulting-RGB = geometry-RGB / sampled-RGB; else if (color blend is average) resulting-RGB = (geometry-RGB * 1/2) + (sampled-RGB * 1/2); if (clamp option set) clamp resulting-RGB between minimum-RGB and maximum-RGB, The analogous computation is done for computing the resulting alpha value. The command requires that there be a camera selected in your scene in order to work properly in -batch or -prompt mode.

Flags:

Long name (short name)		Argument Types	Properties
alphaBlend (abl)		unicode
	When specified, indicates the type of alpha blend to be applied. Options are: “none”, “overwrite”, “add”, “subtract”, “multiply”, “divide”, “average”. This option only applies when colors are being set. The default if this argument is not specified is “overwrite”. The “none” options to not overwrite the existing value.
averageColor (ac)		bool
	When used, will mean to force the storage of shared colors for vertex level sampling. By default vertex level sampling stores unshared colors.
clampAlphaMax (amx)		float
	When used, will mean to clamp the storage of alpha to a maximum
clampAlphaMin (amn)		float
	When used, will mean to clamp the storage of alpha to a minimum
clampRGBMax (cmx)		float, float, float
	When used, will mean to clamp the storage of RGB color to a maximum
clampRGBMin (cmn)		float, float, float
	When used, will mean to clamp the storage of RGB color to a minimum
colorBlend (cbl)		unicode
	When specified, indicates the type of color blend to be applied. Options are: “none”, “overwrite”, “add”, “subtract”, “multiply”, “divide”, “average”. This option only applies when colors are being set. The default if this argument is not specified is “overwrite”. The “none” options to not overwrite the existing value.
colorDisplayOption (cdo)		bool
	Change the display options on the mesh to display the vertex colors.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.
computeShadows (cs)		bool
	When used, shadow maps will be computed, saved, and reused during the sampling process.
displaceGeometry (dg)		bool
	When used, geometry will be displaced along the normals at the sampling positions, as opposed to storing color values. The default is to store colors.
flatShading (fs)		bool
	When used, flat shaded sampling will be computed. The default is smooth shading.
ignoreDoubleSided (ids)		bool
	When specified, the double sided flag will be ignored for prelighting.
lightingOnly (lo)		bool
	When used, incoming illumination will be computed as opposed to surface color an tranparency
reuseShadows (rs)		bool
	When used, if shadow maps were previosly computed and saved, then they will be reused during the sampling process. The computeShadows option must be enabled for this option to apply.
sampleByFace (bf)		bool
	When used, sample will occur at a per face level versus a per vertex level, which is the default behaviour
scaleFactor (sf)		float
	When used, will scale the sampled value by the specified amount. The default scale factor is 1.0. Negative values are acceptable for displacement, but not for color values.
shareUV (su)		bool
	When used, UVs are shared at a vertex when sampled. By default UVs are forced to be unshared.
useLightShadows (ul)		bool
	When used, will use each lights shadow map options. Otherwise these options will be overrridden when the computeShadows, and/or reusedShadows option is enabled.

Derived from mel command maya.cmds.polyGeoSampler

Example:

import pymel.core as pm

# Example 1. Sample for color values.
#    a. No arguments. Will perform sampling of color + transparency at
#     the vertex level, and store color values for affected vertices.
#     No shadows will be computed.
pm.polyGeoSampler()
# b. With shadows and illumination only
pm.polyGeoSampler( lightingOnly=True, computeShadows=True )
# c. Sampling only complete selected faces
pm.polyGeoSampler( sampleByFace=True )
# d. "Flat shading".
# Example 2. Sample for displacement values.
# a. Using displace option
pm.polyGeoSampler( displaceGeometry=True )
# Example 3. Scaling the sampled data.
# a. Scaling option
pm.polyGeoSampler( scaleFactor=0.1 )
# Example 4. Don't force unshared UV value usage, and force
# the storage of shared colors for vertices.
pm.polyGeoSampler( shareUV=True, averageColor=True )
# Example 5. Clamping colors. In this example the alpha and
# RGB channels of the colors are clamped between a min of 0,0,0,1
# and a max of 1,2,1,0.5 .
pm.polyGeoSampler( amn=0.0, amx=0.5, cmn=[0.0,0.0,0.0], cmx=[1.0,2.0,1.0] )
# Example 6. Multiply the new sample color values    with the existing
# colors stored on the geometry, but leave the alpha values
# as they were on the geometry.
pm.polyGeoSampler( colorBlend='multiply', alphaBlend='none' )