[Bf-python] BMesh upgrade docs & api info

[Campbell Barton]

Hi Matt, very reasonable questions. after reading your mail I figured
it'd be best to document (rather then writing a long reply)

This should clear some confusion.
http://www.blender.org/documentation/blender_python_api_2_62_4/bpy.types.Mesh.html#mesh-data

It references bmesh api for more flexible mesh editing and the
gotcha's section for tessface info so script authors should be able to
find useful info a bit more easily.

reply to specific questions inline...

On Tue, Apr 17, 2012 at 11:49 AM, Matt Ebb <matt at mke3.net> wrote:
> 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).

You're right, BMesh api would be overkill here (both for conversion
and memory usage).
Still - keep in mind some modifiers do this - edge-split/bevel - as
long as you do 1 by 1 it shouldn't be _that_ bad.

> 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?

Internally they don't, but to keep user interface and workflows
compatible with 2.62x they are exposed in the UI as one.
What happens under the hood is the UV's are kept in sync with MTexPoly
layer (name and active state).
- I would like to remove this in the future so its possible to add
UV's without texture-face mess.

> 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.

I don't follow, which selected properties are these?

> * 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.

Because it sync's with the uv_texture.active layer... eeh, this should
be documented too.

> * 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.

Hope the example helps here.

> 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.

yes, added this info in docs.

> * 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?

it should be, but its a limitation of our UI list template that it
cant be at the moment. (a fewactive_index properties should be nested
IMHO but we cant - its annoying but not that bad :S)

> I'd appreciate any help here, or even better, if it's all spelled out
> clearly in a doc somewhere :)
>
> cheers and thanks,
>
> Matt
> _______________________________________________
> Bf-python mailing list
> Bf-python at blender.org
> http://lists.blender.org/mailman/listinfo/bf-python



-- 
- Campbell