source/blender/python/api2_2x/doc/Particle.py

   1 # Blender.Object module and the Object PyType object
   2
   3 """
   4 The Blender.Particle submodule
   5
   6
   7 Particle
   8 ========
   9
  10 This module provides access to the B{Particle} in Blender.
  11
  12 @type TYPE: readonly dictionary
  13 @var TYPE: Constant dict used for with L{Particle.TYPE}
  14                 - HAIR: set particle system to hair mode.
  15                 - REACTOR: set particle system to reactor mode.
  16                 - EMITTER: set particle system to emitter mode.
  17 @type DISTRIBUTION: readonly dictionary
  18 @var DISTRIBUTION: Constant dict used for with L{Particle.DISTRIBUTION}
  19                 - GRID: set grid distribution.
  20                 - RANDOM: set random distribution.
  21                 - JITTERED: set jittered distribution.
  22 @type EMITFROM: readonly dictionary
  23 @var EMITFROM: Constant dict used for with L{Particle.EMITFROM}
  24                 - VERTS: set particles emit from vertices
  25                 - FACES: set particles emit from faces
  26                 - VOLUME: set particles emit from volume
  27                 - PARTICLE: set particles emit from particles
  28 @type REACTON: readonly dictionary
  29 @var REACTON: Constant dict used for with L{Particle.REACTON}
  30                 - NEAR: react on near
  31                 - COLLISION: react on collision
  32                 - DEATH: react on death
  33 @type DRAWAS: readonly dictionary
  34 @var DRAWAS: Constant dict used for with L{Particle.DRAWAS}
  35                 - NONE: Don't draw
  36                 - POINT: Draw as point
  37                 - CIRCLE: Draw as circles
  38                 - CROSS: Draw as crosses
  39                 - AXIS: Draw as axis
  40                 - LINE: Draw as lines
  41                 - PATH: Draw pathes
  42                 - OBJECT: Draw object
  43                 - GROUP: Draw goup
  44                 - BILLBOARD: Draw as billboard
  45 @type CHILDTYPE: readonly dictionary
  46 @var CHILDTYPE: Constant dict used for whith L{Particle.CHILDTYPE}
  47                 - NONE: set no children
  48                 - PARTICLES: set children born from particles
  49                 - FACES: set children born from faces
  50 """
  51
  52 class Particle:
  53         """
  54         The Particle object
  55         ===================
  56                 This object gives access to paticles data.
  57
  58         @ivar seed: Set an offset in the random table.
  59         @type seed: int
  60         @ivar type: Type of particle system ( Particle.TYPE[ 'HAIR' | 'REACTOR' | 'EMITTER' ] ).
  61         @type type: int
  62         @ivar resolutionGrid: The resolution of the particle grid.
  63         @type resolutionGrid: int
  64         @ivar startFrame: Frame number to start emitting particles.
  65         @type startFrame: float
  66         @ivar endFrame: Frame number to stop emitting particles.
  67         @type endFrame: float
  68         @ivar editable: Finalize hair to enable editing in particle mode.
  69         @type editable: int
  70         @ivar amount: The total number of particles.
  71         @type amount: int
  72         @ivar multireact: React multiple times ( Particle.REACTON[ 'NEAR' | 'COLLISION' | 'DEATH' ] ).
  73         @type multireact: int
  74         @ivar reactshape: Power of reaction strength, dependent on distance to target.
  75         @type reactshape: float
  76         @ivar hairSegments: Amount of hair segments.
  77         @type hairSegments: int
  78         @ivar lifetime: Specify the life span of the particles.
  79         @type lifetime: float
  80         @ivar randlife: Give the particle life a random variation.
  81         @type randlife: float
  82         @ivar randemission: Emit particles in random order.
  83         @type randemission: int
  84         @ivar particleDistribution: Where to emit particles from  ( Particle.EMITFROM[ 'PARTICLE' | 'VOLUME' | 'FACES' | 'VERTS' ] )
  85         @type particleDistribution: int
  86         @ivar evenDistribution: Use even distribution from faces based on face areas or edge lengths.
  87         @type evenDistribution: int
  88         @ivar distribution: How to distribute particles on selected element ( Particle.DISTRIBUTION[ 'GRID' | 'RANDOM' | 'JITTERED' ] ).
  89         @type distribution: int
  90         @ivar jitterAmount: Amount of jitter applied to the sampling.
  91         @type jitterAmount: float
  92         @ivar pf: Emission locations / face (0 = automatic).
  93         @type pf:int
  94         @ivar invert: Invert what is considered object and what is not.
  95         @type invert: int
  96         @ivar targetObject: The object that has the target particle system (empty if same object).
  97         @type targetObject: Blender object
  98         @ivar targetpsys: The target particle system number in the object.
  99         @type targetpsys: int
 100         @ivar 2d: Constrain boids to a surface.
 101         @type 2d: float
 102         @ivar maxvel: Maximum velocity.
 103         @type maxvel: float
 104         @ivar avvel: The usual speed % of max velocity.
 105         @type avvel: float
 106         @ivar latacc: Lateral acceleration % of max velocity
 107         @type latacc: float
 108         @ivar tanacc: Tangential acceleration % of max velocity
 109         @type tanacc: float
 110         @ivar groundz: Default Z value.
 111         @type groundz: float
 112         @ivar object: Constrain boids to object's surface.
 113         @type object: Blender Object
 114         @ivar renderEmitter: Render emitter object.
 115         @type renderEmitter: int
 116         @ivar displayPercentage: Particle display percentage.
 117         @type displayPercentage: int
 118         @ivar hairDisplayStep: How many steps paths are drawn with (power of 2) in visu mode.
 119         @type hairDisplayStep: int
 120         @ivar hairRenderStep: How many steps paths are rendered with (power of 2) in render mode."
 121         @type hairRenderStep: int
 122         @ivar duplicateObject: Get the duplicate object.
 123         @type duplicateObject: Blender Object
 124         @ivar drawAs: Get draw type Particle.DRAWAS([ 'NONE' | 'OBJECT' | 'POINT' | ... ]).
 125         @type drawAs: int
 126         @ivar childAmount: The total number of children
 127         @type childAmount: int
 128         @ivar childType: Type of childrens ( Particle.CHILDTYPE[ 'FACES' | 'PARTICLES' | 'NONE' ] )
 129         @type childType: int
 130         @ivar childRenderAmount: Amount of children/parent for rendering
 131         @type childRenderAmount: int
 132         @ivar childRadius: Radius of children around parent
 133         @type childRadius: float
 134         @ivar childRound: Roundness of children around parent
 135         @type childRound: float
 136         @ivar childClump: Amount of clumpimg
 137         @type childClump: float
 138         @ivar childShape: Shape of clumpimg
 139         @type childShape: float
 140         @ivar childSize: A multiplier for the child particle size
 141         @type childSize: float
 142         @ivar childRand: Random variation to the size of the child particles
 143         @type childRand: float
 144         @ivar childRough1: Amount of location dependant rough
 145         @type childRough1: float
 146         @ivar childRough1Size: Size of location dependant rough
 147         @type childRough1Size: float
 148         @ivar childRough2: Amount of random rough
 149         @type childRough2: float
 150         @ivar childRough2Size: Size of random rough
 151         @type childRough2Size: float
 152         @ivar childRough2Thresh: Amount of particles left untouched by random rough
 153         @type childRough2Thresh: float
 154         @ivar childRoughE: Amount of end point rough
 155         @type childRoughE: float
 156         @ivar childRoughEShape: Shape of end point rough
 157         @type childRoughEShape: float
 158         @ivar childKink: Type of periodic offset on the path (Particle.CHILDKINK[ 'BRAID' | 'WAVE' | 'RADIAL' | 'CURL' | 'NOTHING' ])
 159         @type childKink: int
 160         @ivar childKinkAxis: Which axis to use for offset (Particle.CHILDKINKAXIS[ 'Z' | 'Y' | 'X' ])
 161         @type childKinkAxis: int
 162         @ivar childKinkFreq: The frequency of the offset (1/total length)
 163         @type childKinkFreq: float
 164         @ivar childKinkShape: Adjust the offset to the beginning/end
 165         @type childKinkShape: float
 166         @ivar childKinkAmp: The amplitude of the offset
 167         @type childKinkAmp: float
 168         @ivar childBranch: Branch child paths from eachother
 169         @type childBranch: int
 170         @ivar childBranch: Animate branching
 171         @type childBranch: int
 172         @ivar childBranch: Start and end points are the same
 173         @type childBranch: int
 174         @ivar childBranch: Threshold of branching
 175         @type childBranch: float
 176         """
 177
 178         def freeEdit():
 179                 """
 180                 Free edit mode.
 181                 @return: None
 182                 """
 183
 184         def getLoc(all=0,id=0):
 185                 """
 186                 Get the particles locations.
 187                 A list of tuple is returned in particle mode.
 188                 A list of list of tuple is returned in hair mode.
 189                 The tuple is a vector of 3 or 4 floats in world space (x,y,z, optionally the particle's id).
 190                 @type all: int
 191                 @param all: if not 0 export all particles (uninitialized (unborn or died)particles exported as None).
 192                 @type id: int
 193                 @param id: add the particle id in the end of the vector tuple
 194                 @rtype: list of vectors (tuple of 3 floats and optionally the id) or list of list of vectors
 195                 @return: list of vectors or list of list of vectors (hair mode) or None if system is disabled
 196                 """
 197         def getRot(all=0,id=0):
 198                 """
 199                 Get the particles' rotations as quaternion.
 200                 A list of tuple is returned in particle mode.
 201                 The tuple is vector of 4 or 5 floats (x,y,z,w, optionally the id of the particle).
 202
 203                 @type all: int
 204                 @param all: if not 0, export all particles (uninitialized (unborn or died) particles exported as None).
 205                 @type id: int
 206                 @param id: add the particle id in the return tuple
 207                 @rtype: list of tuple of 4 or 5 elements (if id is not zero)
 208                 @return: list of 4-tuples or None if system is disabled
 209                 """
 210
 211         def getMat():
 212                 """
 213                 Get the particles' material.
 214                 @rtype: Blender Material
 215                 @return: The material assigned to particles
 216                 """
 217
 218         def getSize(all=0,id=0):
 219                 """
 220                 Get the particles' size.
 221                 A list of float or list of tuple (particle's size,particle's id).
 222                 @type all: int
 223                 @param all: if not 0, export all particles (uninitialized (unborn or died) particles exported as None).
 224                 @type id: int
 225                 @param id: add the particle id in the return tuple
 226                 @rtype: list of floats
 227                 @return: list of floats or list of tuples if id is not zero (size,id) or None if system is disabled.
 228                 """
 229
 230         def getAge(all=0,id=0):
 231                 """
 232                 Get the particles' age.
 233                 A list of float or list of tuple (particle's age, particle's id).
 234                 @type all: int
 235                 @param all: if not 0, export all particles (uninitialized (unborn or died) particles exported as None).
 236                 @type id: int
 237                 @param id: add the particle id in the return tuple
 238                 @rtype: list of floats
 239                 @return: list of floats or list of tuples if id is not zero (size,id) or None if system is disabled.
 240                 """