Define name of built-in attributes #82693

New Issue

Dalai Felinto · 2020-11-13T15:55:43+01:00

Dalai Felinto commented

2020-11-13 15:55:43 +01:00

Naming rule for attributes

built-in attribute use "snake_case"
- position
- rotation
- radius
user defined attributes are initialiazed as "PascalCase", but can be renamed later to anything (unicodes, space, lowercase)
- Col
- Group
- UVMap
- FaceMap
- Key

In both cases abbreviations are to be avoided. If they eventually happen, should be lower case for the built-in attributes. For user defined attributes they can be decided on a per-case basis.

Reference

lowercase
snake_case
camelCase
PascalCase
A combination of snake and camel case Written_Like_This

MaterialX: lowercase .e.g materialassign, variantset (example)

Blender datablocks uses "Title Case" and PascalCase:

View Layer
ParticleSettings

Built-in attributes:

density
position
radius
rotation
scale
temperature

Design presented on: https://wiki.blender.org/wiki/Source/Nodes/Modifier_Nodes#Attributes

Naming rule for attributes **** * built-in attribute use "snake_case" * position * rotation * radius * user defined attributes are initialiazed as "PascalCase", but can be renamed later to anything (unicodes, space, lowercase) * Col * Group * UVMap * FaceMap * Key In both cases abbreviations are to be avoided. If they eventually happen, should be lower case for the built-in attributes. For user defined attributes they can be decided on a per-case basis. Reference **** * lowercase * snake_case * camelCase * PascalCase * A combination of snake and camel case `Written_Like_This` MaterialX: lowercase .e.g `materialassign, variantset` ([example](https://graphics.pixar.com/usd/docs/api/usd_mtlx_page_front.html)) Blender datablocks uses "Title Case" and PascalCase: * View Layer * ParticleSettings Built-in attributes: **** * `density` * `position` * `radius` * `rotation` * `scale` * `temperature` Design presented on: https://wiki.blender.org/wiki/Source/Nodes/Modifier_Nodes#Attributes

Dalai Felinto commented

2020-11-13 15:55:43 +01:00

Added subscriber: @dfelinto

Pablo Vazquez commented

2020-11-19 16:15:29 +01:00

Added subscriber: @pablovazquez

Pablo Vazquez commented

2020-11-19 16:15:29 +01:00

I think we should try to keep names shorter, since they will be used a lot in expressions.
Possibly supporting multiple names for built-in attributes. A longer, more descriptive name and a short-form version.

Proposal:

Location: P, position, (also location for compatibility?)
Rotation: R, rotation (also orientation, orient for compatibility?)
Scale: S, scale

Other names we could have by default for points/particles:

Age: age
Density: density
Temperature: temperature
Normal: N, normal
Velocity: V, velocity
Radius: r, radius
Point Number: index
Up (vector pointing up): up

I think we should try to keep names shorter, since they will be used a lot in expressions. Possibly supporting multiple names for built-in attributes. A longer, more descriptive name and a short-form version. Proposal: * Location: `P`, `position`, (also `location` for compatibility?) * Rotation: `R`, `rotation` (also `orientation`, `orient` for compatibility?) * Scale: `S`, `scale` Other names we could have by default for points/particles: * Age: `age` * Density: `density` * Temperature: `temperature` * Normal: `N`, `normal` * Velocity: `V`, `velocity` * Radius: `r`, `radius` * Point Number: `index` * Up (vector pointing up): `up`

Steffen Dünner commented

2020-11-19 16:32:34 +01:00

Added subscriber: @SteffenD

Jacques Lucke commented

2020-11-19 19:03:04 +01:00

Added subscriber: @JacquesLucke

Jacques Lucke commented

2020-11-19 19:03:04 +01:00

Can we get a set of rules for the names? Should the names be lower case always/usually. What about spaces? Should underscores be used instead? Do we want to enforce these rules (could be useful for expressions)?
What do we do if existing vertex groups do not follow these rules, are they just not accessible in geometry nodes?

I think giving attributes multiple names is calling for trouble. Having a single name will make things simpler. Maybe it makes sense to provide tooltips for some common attributes like P, but not sure if it is worth it.

Can we get a set of rules for the names? Should the names be lower case always/usually. What about spaces? Should underscores be used instead? Do we want to enforce these rules (could be useful for expressions)? What do we do if existing vertex groups do not follow these rules, are they just not accessible in geometry nodes? I think giving attributes multiple names is calling for trouble. Having a single name will make things simpler. Maybe it makes sense to provide tooltips for some common attributes like P, but not sure if it is worth it.

Brecht Van Lommel commented

2020-11-23 16:30:48 +01:00

Added subscriber: @brecht

Brecht Van Lommel commented

2020-11-23 16:30:48 +01:00

Talked to Dalai and Bastien about this, summarizing some of the points I made:

Most existing data names in Blender are capitalized full words, and in the few cases where multiple words are used they use camel case rather than spaces. This also goes for uv maps and vertex colors, which are also a type of attribute. The current naming was intended to be consistent with that.
We could also aim for interop with other applications, especially for file formats like USD, Alembic. Unfortunately there is no universal convention there, and names are often cryptic abbreviations that have no clear meaning in Blender. Those names can be translated to/from Blender conventions on import/export, which is only a heuristic but should work ok in practice. Also note that you'd have to do this type of translations for e.g. MaterialX shaders reading attributes, not just the geometry itself.
To the extent that there is a convention in similar 3D apps, it seems to be either an abbreviation with capital letter (P, Pref, Cd) or a lowecase name (uv, st, width, pscale, ..)
For volumes we use lowercase names for grids (density and temperature), because that is the OpenVDB convention.
I would not support multiple names for the same attributes, makes it harder to follow docs, tutorials, and interchange .blend or other files. Builtin geometry nodes can hide the difference to some extent, but at some point that stops and users have to deal with incompatibilities.
I would not strictly enforce conventions about case or spaces, for consistency with the rest of Blender and for easier interop with other apps. I would not use spaces and underscores by default but still allow them.
Rotation and orientation are like scale and size, one is relative the other is absolute. For instancing, I think relative terms make most sense. And they also makes sense for point clouds as a multiplier on some global radius.

Personally my recommendation is not to use abbreviations at all, which makes it a choice between capitialization or all-lowercase. Either works for me, depends if we prefer to be consistent with other default Blender data names, or if we consider it harmful or helpful that geometry attributes have a distinct naming convention. If we do change it to lowercase, I'd recommend changing default uv map and vertex color names to lowercase as well.

Talked to Dalai and Bastien about this, summarizing some of the points I made: * Most existing data names in Blender are capitalized full words, and in the few cases where multiple words are used they use camel case rather than spaces. This also goes for uv maps and vertex colors, which are also a type of attribute. The current naming was intended to be consistent with that. * We could also aim for interop with other applications, especially for file formats like USD, Alembic. Unfortunately there is no universal convention there, and names are often cryptic abbreviations that have no clear meaning in Blender. Those names can be translated to/from Blender conventions on import/export, which is only a heuristic but should work ok in practice. Also note that you'd have to do this type of translations for e.g. MaterialX shaders reading attributes, not just the geometry itself. * To the extent that there is a convention in similar 3D apps, it seems to be either an abbreviation with capital letter (`P`, `Pref`, `Cd`) or a lowecase name (`uv`, `st`, `width`, `pscale`, ..) * For volumes we use lowercase names for grids (`density` and `temperature`), because that is the OpenVDB convention. * I would not support multiple names for the same attributes, makes it harder to follow docs, tutorials, and interchange .blend or other files. Builtin geometry nodes can hide the difference to some extent, but at some point that stops and users have to deal with incompatibilities. * I would not strictly enforce conventions about case or spaces, for consistency with the rest of Blender and for easier interop with other apps. I would not use spaces and underscores by default but still allow them. * Rotation and orientation are like scale and size, one is relative the other is absolute. For instancing, I think relative terms make most sense. And they also makes sense for point clouds as a multiplier on some global radius. Personally my recommendation is not to use abbreviations at all, which makes it a choice between capitialization or all-lowercase. Either works for me, depends if we prefer to be consistent with other default Blender data names, or if we consider it harmful or helpful that geometry attributes have a distinct naming convention. If we do change it to lowercase, I'd recommend changing default uv map and vertex color names to lowercase as well.

Jacques Lucke commented

2020-11-23 16:56:27 +01:00

Thanks for the feedback. I don't have a strong opinion on whether capitalization or all-lowercase should be the convention then.

Brecht Van Lommel commented

2020-11-23 17:42:36 +01:00

Also should mention that vertex groups are capitalized and I imagine will be accessible as attributes in geometry nodes. And those names are matched with bone names for armature deform. Changing to lowercase may just be more trouble than it is worth.

The volume grids inconsistency is not great. We could also capitalize/lowercase on import/export there. For render engines that directly read OpenVDB or USD files any renaming on import/export is also a pain, but I guess they have to deal with that regardless of the convention we choose.

Also should mention that vertex groups are capitalized and I imagine will be accessible as attributes in geometry nodes. And those names are matched with bone names for armature deform. Changing to lowercase may just be more trouble than it is worth. The volume grids inconsistency is not great. We could also capitalize/lowercase on import/export there. For render engines that directly read OpenVDB or USD files any renaming on import/export is also a pain, but I guess they have to deal with that regardless of the convention we choose.

Dalai Felinto commented

2020-11-24 14:32:58 +01:00

@pablovazquez and I came up with this proposal:

built-in attribute use "snake_case"
- position
- rotation
- radius
user defined attributes are initialiazed as "PascalCase", but can be renamed later to anything (unicodes, space, lowercase)
- Col
- Group
- UVMap
- FaceMap
- Key

Reference

lowercase
snake_case
camelCase
PascalCase
A combination of snake and camel case Written_Like_This

MaterialX: lowercase .e.g materialassign, variantset (example)

Blender datablocks uses "Title Case" and PascalCase:

View Layer
ParticleSettings

@pablovazquez and I came up with this proposal: * built-in attribute use "snake_case" * position * rotation * radius * user defined attributes are initialiazed as "PascalCase", but can be renamed later to anything (unicodes, space, lowercase) * Col * Group * UVMap * FaceMap * Key Reference **** * lowercase * snake_case * camelCase * PascalCase * A combination of snake and camel case `Written_Like_This` MaterialX: lowercase .e.g `materialassign, variantset` ([example](https://graphics.pixar.com/usd/docs/api/usd_mtlx_page_front.html)) Blender datablocks uses "Title Case" and PascalCase: * View Layer * ParticleSettings

Brecht Van Lommel commented

2020-11-24 14:50:23 +01:00

I'm fine with that proposal.

Sergey Sharybin commented

2020-11-25 14:26:05 +01:00

Added subscriber: @Sergey

Sergey Sharybin commented

2020-11-25 14:26:05 +01:00

Background: I was randomly pointed to this task.

Here are two easy steps to dramatically improve quality of the proposal.

Have up-to-date conclusion in the task description. Just similar to what we do for reports. Make it easy for everyone to see what's what.
Explicitly cover abbreviations. If they are unused at all, state so. If they are forbidden, state so. If there are any case when they might appear from (user attributes, for example) make explicit whether it is only first letter to be capital, or all of them (within the abbreviation).

Background: I was randomly pointed to this task. Here are two easy steps to dramatically improve quality of the proposal. 1. Have up-to-date conclusion in the task description. Just similar to what we do for reports. Make it easy for everyone to see what's what. 2. Explicitly cover abbreviations. If they are unused at all, state so. If they are forbidden, state so. If there are any case when they might appear from (user attributes, for example) make explicit whether it is only first letter to be capital, or all of them (within the abbreviation).

Dalai Felinto commented

2020-11-26 12:41:53 +01:00

Migrated the text to the wiki: https://wiki.blender.org/wiki/Source/Nodes/Modifier_Nodes#Attributes

Dalai Felinto commented

2020-11-26 12:55:01 +01:00

@Sergey thanks for the feedback. I addressed your 1st point. For the second I feel it is a bit premature to set a rule to a case I can't even think already. So I phrased in a way that leaves some leeway for when it comes to that while covering it for built-in attributes.

Dalai Felinto commented

2020-11-30 09:27:26 +01:00

Changed status from 'Needs Triage' to: 'Resolved'

Dalai Felinto closed this issue

2020-11-30 09:27:26 +01:00

Dalai Felinto self-assigned this 2020-11-30 09:27:26 +01:00

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Define name of built-in attributes #82693