Go to: Synopsis. Return value. Keywords.
Related. Flags.
Python examples.
polyGeoSampler([alphaBlend=string], [averageColor=boolean], [clampAlphaMax=float], [clampAlphaMin=float], [clampRGBMax=[float, float, float]],
[clampRGBMin=[float, float,
float]], [colorBlend=string], [colorDisplayOption=boolean],
[computeShadows=boolean],
[displaceGeometry=boolean],
[flatShading=boolean],
[ignoreDoubleSided=boolean],
[lightingOnly=boolean],
[reuseShadows=boolean],
[sampleByFace=boolean],
[scaleFactor=float],
[shareUV=boolean], [useLightShadows=boolean])
Note: Strings representing object names and
arguments must be separated by commas. This is not depicted in the
synopsis.
polyGeoSampler is undoable, NOT queryable, and
editable.
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.
| boolean |
Success or Failure |
poly, sampling, GeoSampler
polyColorPerVertex
alphaBlend, averageColor, clampAlphaMax, clampAlphaMin, clampRGBMax, clampRGBMin, colorBlend, colorDisplayOption, computeShadows, displaceGeometry, flatShading, ignoreDoubleSided, lightingOnly, reuseShadows, sampleByFace, scaleFactor, shareUV, useLightShadows
| Long name (short name) |
Argument types |
Properties |
sampleByFace(bf) |
boolean |
  |
|
When used, sample will occur at a per face level versus a per
vertex level, which is the default behaviour |
|
computeShadows(cs) |
boolean |
|
|
When used, shadow maps will be computed, saved, and reused
during the sampling process. |
|
useLightShadows(ul) |
boolean |
|
|
When used, will use each lights shadow map options. Otherwise
these options will be overrridden when the computeShadows, and/or
reusedShadows option is enabled. |
|
reuseShadows(rs) |
boolean |
|
|
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. |
|
lightingOnly(lo) |
boolean |
|
|
When used, incoming illumination will be computed as opposed to
surface color an tranparency |
|
flatShading(fs) |
boolean |
|
|
When used, flat shaded sampling will be computed. The default
is smooth shading. |
|
displaceGeometry(dg) |
boolean |
|
|
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. |
|
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) |
boolean |
|
|
When used, UVs are shared at a vertex when sampled. By default
UVs are forced to be unshared. |
|
averageColor(ac) |
boolean |
|
|
When used, will mean to force the storage of shared colors for
vertex level sampling. By default vertex level sampling stores
unshared colors. |
|
clampRGBMin(cmn) |
[float, float, float] |
|
|
When used, will mean to clamp the storage of RGB color to a
minimum |
|
clampRGBMax(cmx) |
[float, float, float] |
|
|
When used, will mean to clamp the storage of RGB color to a
maximum |
|
clampAlphaMin(amn) |
float |
|
|
When used, will mean to clamp the storage of alpha to a
minimum |
|
clampAlphaMax(amx) |
float |
|
|
When used, will mean to clamp the storage of alpha to a
maximum |
|
colorBlend(cbl) |
string |
|
|
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. |
|
alphaBlend(abl) |
string |
|
|
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. |
|
ignoreDoubleSided(ids) |
boolean |
|
|
When specified, the double sided flag will be ignored for
prelighting. |
|
colorDisplayOption(cdo) |
boolean |
|
|
Change the display options on the mesh to display the vertex
colors. |
|
| Flag can appear in Create mode of
command |
Flag can appear in Edit mode of command |
 Flag can appear in Query mode of command |
 Flag can have multiple arguments, passed
either as a tuple or a list. |
import maya.cmds as cmds
# 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.
cmds.polyGeoSampler()
# b. With shadows and illumination only
cmds.polyGeoSampler( lightingOnly=True, computeShadows=True )
# c. Sampling only complete selected faces
cmds.polyGeoSampler( sampleByFace=True )
# d. "Flat shading".
# Example 2. Sample for displacement values.
# a. Using displace option
cmds.polyGeoSampler( displaceGeometry=True )
# Example 3. Scaling the sampled data.
# a. Scaling option
cmds.polyGeoSampler( scaleFactor=0.1 )
# Example 4. Don't force unshared UV value usage, and force
# the storage of shared colors for vertices.
cmds.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 .
cmds.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.
cmds.polyGeoSampler( colorBlend='multiply', alphaBlend='none' )