ngPlant HLI documentation (Python)


Overview

ngPlant high-level interface (implemented in _ngp module) allows to use designed plant models in different kinds of applications. It allows to create plant import/export plugins using Python programming language. It is even possible to create simple plant model viewers using pygame and pyopengl libraries.

This document describes versions 0.9.5-0.9.12 of _ngp module.


Building

On UNIX-like systems _ngp module is built together with other ngPlant libraries and applications. Python development package is required for _ngp module compilation and linkage.

_ngp module can be built on Windows systems too. To build it under Windows you must use the same compiler which was used to compile your Python interpreter.

Then compilation process will be done, you will have _ngp.so or _ngp.dll library in pywrapper directory.


Changes made in 0.9.13


Changes made in 0.9.5


Changes made in 0.9.4


Changes made in 0.9.3


Usage

To use _ngp module you need to import it first:

 import _ngp
, or
 from _ngp import *

To understand some basic concepts behind ngPlant high-level interface you should read Definitions section of C++ HLI documentation.

scripts directory in source tarball contains script ngp2obj.py, which can be used as an example of _ngp module usage.

Classes summary
Name Short description
PlantInstance Plant instance class
BranchGroup Branch group class
ModelMetaInfo Model meta information class
MaterialDef Material description class

PlantInstance

Objects of this class represent single instances of plant model.

Methods summary
Name Short description
__init__ Constructor
GetMetaInfo Return meta information about model
GetGroupCount Return branch group count
GetGroup Return branch group
GetBoundingBox Return plant model bounding box

Method __init__
  __init__(filename,seed = 0)

Create new plant instance. Plant model is loaded from file filename and instance of plant is created using seed as a seed for random number generator. Using different seeds you can get almost infinite number of similar but slightly different plant models. If argument seed is omitted, or equal to zero, default seed will be used.


Method GetMetaInfo
  GetMetaInfo()

Return meta information about model such as author, license and other (ModelMetaInfo).


Method GetGroupCount
  GetGroupCount()

Return total count of branch groups in plant instance.


Method GetGroup
  GetGroup(index)

Return branch group object (BranchGroup). index argument is an index of branch group and must be in range 0 .. instance.GetGroupCount()-1.


Method GetBoundingBox
  GetBoundingBox()

Return bounding box of plant model. Result has type ((float,float,float),(float,float,float)), where first tuple contains min. X,Y and Z values and second tuple contains max. X,Y and Z values of bounding box.


BranchGroup

This class represents branch group. It contains methods for getting information about branch group such as: material description, branch count, vertex attributes and model topology.

Methods summary
Name Short description
__init__ Constructor
GetName Return branch group name
GetMaterial Return description of branch group material
GetBillboardSize Return size of branch group billboards
IsLODVisRangeEnabled Return state of LOD visibility range
GetLODVisRange Return LOD visibility range
GetBranchCount Return count of branches in a branch group
GetVAttrCount Return count of different attribute values in a branch group (detailed mode)
GetVAttrBuffer Return array of vertex attributes (detailed mode)
GetPrimitiveCount Return count of primitives (detailed mode)
GetPrimitiveType Return type of primitive (detailed mode)
GetVAttrIndexBuffer Return array of tuples with attribute indices (detailed mode)
GetVAttrCountI Return count of attribute values (vertex count) in a branch group (indexed mode)
GetVAttrBufferI Return array of vertex attributes (indexed mode)
GetIndexCount Return count of indices, required to describe branch or branch group model, using given primitive type (indexed mode)
GetIndexBuffer Return array of vertex indices (indexed mode)

Method __init__
  __init__(instance,group_index)

This method constructs branch group objects. You should not create objects of this class directly - GetGroup method of PlantInstance must be used to get references to BranchGroup objects.


Method GetName
  GetName()

Return branch group name.


Method GetMaterial
  GetMaterial()

Return description of branch group material. This method returns object of MaterialDef class.


Method GetBillboardSize
  GetBillboardSize()

Return tuple (width,height) containing width and height of branch group billboards. Use this method for billboard branch groups only.


Method IsLODVisRangeEnabled
  IsLODVisRangeEnabled()

Return true if LOD visibility range must be taken into account while rendering branch group and false if branch group is visible at any LOD.


Method GetLODVisRange
  GetLODVisRange()

Return tuple (MinLOD,MaxLOD) with minimal and maximum LOD values at which branch group is visible.


Method GetBranchCount
  GetBranchCount()

Return count of branches in a branch group.


Method GetVAttrCount
  GetVAttrCount(attr,total = 0)

Return count of different attribute values in a branch group.

attr - type of attribute in question. attr must be one of: ATTR_VERTEX, ATTR_NORMAL, ATTR_TEXCOORD0.

If total is equal to 0, count of attribute values of single branch will be returned. Count of different attribute values in all branches of branch group will be returned if total is non-zero.


Method GetVAttrBuffer
  GetVAttrBuffer(attr)

Return array of vertex attributes. attr must be one of: ATTR_VERTEX, ATTR_NORMAL, ATTR_TEXCOORD0.

If attr is ATTR_VERTEX or ATTR_NORMAL, return value will be an array of 3-float tuples. If attr is ATTR_TEXCOORD0, return value will be an array of 2-float tuples.


Method GetPrimitiveCount
  GetPrimitiveCount(total = 1)

Return count of primitives in a single branch or in a branch group in a whole. If total is zero, count of primitives in a single branch will be returned. If total is not a zero, count of primitives in all branches of branch group will be returned.


Method GetPrimitiveType
  GetPrimitiveType(index,total = 1)

Return type of indexth primitive. If total is not a zero, primitive index will be treated as and index in array of primitives in branch group. If total is a zero, primitive index will be treated as and index in array of primitives in a single branch.

Result value may be one of TRIANGLE or QUAD.


Method GetVAttrIndexBuffer
  GetVAttrIndexBuffer(attr,total = 1,base = 0)

This method return array of tuples. Each tuple contains attribute indices for a single primitive. Attribute type is selected by attr and must be one of ATTR_VERTEX, ATTR_NORMAL, ATTR_TEXCOORD0. If total is zero, array will contain indices for one branch. If total is non-zero (default), array will contain indices for all branches of branch group. Optional base value may be added to all index values.


Method GetVAttrCountI
  GetVAttrCountI(total = 0)

Return count of different attribute values in single branch or in all branches of branch group. In fact, it is a count of vertices in a single branch model or in all branches of branch group.

If total is equal to 0 (default), count of vertices in single branch will be returned. Count of vertices in all branches of branch group will be returned if total is non-zero.


Method GetVAttrBufferI
  GetVAttrBufferI(attr)

Return array of vertex attributes. attr must be one of: ATTR_VERTEX, ATTR_NORMAL, ATTR_TEXCOORD0. If branch group is rendered in billboard mode, ATTR_BILLBOARD_POS may be passed in attr to get array of billboard positions in model space.

If attr is ATTR_VERTEX, ATTR_NORMAL or ATTR_BILLBOARD_POS, return value will be an array of 3-float tuples. If attr is ATTR_TEXCOORD0, return value will be an array of 2-float tuples.


Method GetIndexCount
  GetIndexCount(primitive_type,total = 1)

Return size of index buffer which is required to describe branch geometry using primitive_type. primitive_type must be TRIANGLE_LIST.

If total is equal to 0, count of indices in a single branch model will be returned. Count of indices, required to describe geometry of all branches in branch group, will be returned if total is non-zero (default).


Method GetIndexBuffer
  GetIndexBuffer(primitive_type,total = 1,base = 0)

Return array of vertex indices required to create branch model using primitive_type primitives. primitive_type must be TRIANGLE_LIST. Optional base may be added to all index values.

If total is equal to 0, array of indices for a single branch model will be returned. Array of indices, required to describe geometry of all branches in branch group, will be returned if total is non-zero (default).


ModelMetaInfo

This class contains meta information about model such as author, license and so on. Note: only constant methods are described below.
Attributes summary
Name Short description
Author Author information
LicenseName License name
LicenseURL License URL
PlantInfoURL Plant description URL

MaterialDef

This class describes material properties.

Methods summary
Name Short description
__init__ Initialize new material object
Attributes summary
Name Short description
Color Material color (R,G,B) tuple
TexNames List of texture names
DoubleSided Material double-sided property
Transparent Material transparency property
Billboard Material billboard property
BillboardMode Billboard mode property
AlphaCtrlEnabled Alpha control state
AlphaFadeRange Tuple, containing AlphaFadeIn and AlphaFadeOut values

Method __init__
  __init__((r,g,b),tex_name,double_sided,transparent,billboard,alpha_ctrl_enabled,(alpha_fade_in,alpha_fade_out))

Initialize material description. You should not create objects of this class yourself - use GetMaterial() method of BranchGroup to get objects of this class.