[Bf-python] BMesh upgrade docs & api info

[Matt Ebb]

On Fri, Mar 23, 2012 at 12:41 PM, Campbell Barton <ideasman42 at gmail.com> wrote:
> Hi List, its been a while since I posted to the list on bmesh python
> api progress and related issues.

Hi, I'm trying to update my render exporter to deal with the new mesh
structure and I'm finding it quite difficult and confusing. The
'gotchas' page is quite good, but the rest of the docs seem to be
quite scattered - is there an overall page that I may have missed that
explains how this all fits together? This page (
http://wiki.blender.org/index.php/Dev:2.6/Source/Modeling/BMesh/Design
) is not bad as an overview, but doesn't help much with python, or
with anything more than verts/edges/loops/polys.

In particular I'm trying to figure out how to export data such as UVs,
vertex colours, etc to be rendered. Renderman supports ngons just
fine, and that's how I'd like to export the data. I'd really rather
not use the bmesh python API, since I presume creating and destroying
bmeshes will add additional CPU and memory costs, which shouldn't be
necessary just to export data, right? So far exporting the geometry
itself goes fine (iterating over vertices and polygons).

For UVs now I'm having more trouble. I've been looking in the
datablocks view of the outliner to try and figure out how it all
works, and it seems there's now a distinction between 'UV Map' and 'UV
loop layer'. How do these two relate to each other?

At the moment I'm assuming that a UV Map contains the link to a
per-face image, but it also seems to contain a weird collection of 4
'UV Selected' properties, that I can't figure out what on earth
they're for. The names of UV Maps also seem to correlate with what's
in the UI.

* Poking in the python console, I see that mesh.uv_loop_layers has an
'active' property, that's not displayed in the UI in datablocks mode
(why?). This seems to get me the active layer selected in the UI.

* UV Loop layers seem to contain the UV coordinates themselves (a uv
pair for each per-face-vertex 'loop') inside 'data', but I can't see
how to relate those to the UV Maps shown in the UI. When I iterate
over the uv loop layers (eg. [l for l in mesh.uv_loop_layers] ) it
gives me names like: bpy.data.meshes['Cube'].uv_loop_layer["UV
coord"]. These names are not visible in the datablocks view, and do
not seem to correspond to the names in the 'UV Maps' in the UI.

How can I find the right UV loop layer based on the name of a UV Map ?
In my simple test file here it looks like they share indices in their
respective collections, but can this always be relied upon?

* I'm assuming that the vertex colours are ordered by index to
correspond with loops? It would be nice if this were documented
explicitly.

* Side note: All these Clone/Mask UV Map/Clone UV Map Index/Clone UV
loop layer/Clone UV loop layer index is pretty messy in the datablocks
- does it need a sub-section?


I'd appreciate any help here, or even better, if it's all spelled out
clearly in a doc somewhere :)

cheers and thanks,

Matt