Welcome to Python-flavored Magnum! Please note that, while already being
rather stable, this functionality is still considered experimental and
some APIs might get changed without preserving full backwards compatibility.
SceneFieldData class
Scene field data
Associates a pair of typed data views with a name, type and other scene field properties, which can be subsequently put into a SceneData instance, for example with scenetools.combine_fields(). The mapping data view is always one-dimensional. The field data view can be either one-dimensional, for example a NumPy array:
mapping_data = array.array('I', [0, 2, 7]) field_data = np.array([(-0.5, 0.0), (+0.5, 0.0), ( 0.0, 0.5)], dtype='2f') translations = trade.SceneFieldData(trade.SceneField.TRANSLATION, trade.SceneMappingType.UNSIGNED_INT, mapping_data, trade.SceneFieldType.VECTOR2, field_data)
Or it can be two-dimensional, for example by expanding a flat array into a list of two-component vectors:
field_data = array.array('f', [-0.5, 0.0, +0.5, 0.0, 0.0, 0.5]) translations = trade.SceneFieldData(trade.SceneField.TRANSLATION, trade.SceneMappingType.UNSIGNED_INT, mapping_data, trade.SceneFieldType.VECTOR2, containers.StridedArrayView1D(field_data).expanded(0, (3, 2)))
Memory ownership and reference counting
On initialization, the instance inherits the
containers.StridedArrayView1D.owner
objects of both views, storing it in the mapping_owner and
field_owner fields, meaning that calling del on the original
data will not invalidate the instance.
Data access
Similarly to SceneData, the class makes use of Python’s dynamic
nature and provides direct access to attribute data in their concrete type
via mapping_data and field_data. However, the
SceneFieldData is considered a low level API and thus a
containers.StridedArrayView2D
/ containers.StridedBitArrayView2D
is returned always for field data, even for non-array attributes. The
returned views inherit the mapping_owner or field_owner and
element access coverts to a type corresponding to a particular
SceneMappingType or SceneFieldType. For example, extracting
the data from the translations field created above:
>>> mapping = translations.mapping_data >>> field = translations.field_data >>> mapping.owner is mapping_data True >>> field.owner is field_data True >>> mapping[2] 7 >>> field[2][0] Vector(0, 0.5)
Special methods
- def __init__(self, name: SceneField, mapping_type: SceneMappingType, mapping_data: corrade.containers.StridedArrayView1D, field_type: SceneFieldType, field_data: corrade.containers.StridedArrayView1D, *, field_array_size: int = 0, flags: SceneFieldFlags = SceneFieldFlags.NONE) -> None
- Construct from a 1D field view
- def __init__(self, name: SceneField, mapping_type: SceneMappingType, mapping_data: corrade.containers.StridedArrayView1D, field_type: SceneFieldType, field_data: corrade.containers.StridedArrayView2D, *, field_array_size: int = 0, flags: SceneFieldFlags = SceneFieldFlags.NONE) -> None
- Construct from a 2D field view
- def __init__(self, name: SceneField, mapping_type: SceneMappingType, mapping_data: corrade.containers.StridedArrayView1D, field_data: corrade.containers.StridedBitArrayView1D, *, flags: SceneFieldFlags = SceneFieldFlags.NONE) -> None
- Construct a bit field
- def __init__(self, name: SceneField, mapping_type: SceneMappingType, mapping_data: corrade.containers.StridedArrayView1D, field_data: corrade.containers.StridedBitArrayView2D, *, flags: SceneFieldFlags = SceneFieldFlags.NONE) -> None
- Construct an array bit field
Properties
- field_array_size: int get
- Field array size
- field_data: object get
- Field data
- field_owner: object get
- Field memory owner
- field_type: SceneFieldType get
- Field type
- flags: SceneFieldFlags get
- Field flags
- mapping_data: corrade.containers.StridedArrayView1D get
- Object mapping data
- mapping_owner: object get
- Mapping memory owner
- mapping_type: SceneMappingType get
- Object mapping type
- name: SceneField get
- Field name
- size: int get
- Number of entries
Method documentation
def magnum.
Construct from a 1D field view
| Exceptions | |
|---|---|
| AssertionError | If mapping_data and field_data don’t have
the same size |
| AssertionError | If field_type is not valid for name |
| AssertionError | If field_type is a string type or
SceneFieldType.BIT |
| AssertionError | If mapping_data stride doesn’t fit into 16 bits |
| AssertionError | If mapping_data format size is smaller than
size of mapping_type |
| AssertionError | If field_data stride doesn’t fit into 16 bits |
| AssertionError | If field_data format size is smaller than size
of field_type at given field_array_size |
| AssertionError | If field_array_size is non-zero and name
can’t be an array field |
| AssertionError | If flags contain
SceneFieldFlags.OFFSET_ONLY,
SceneFieldFlags.NULL_TERMINATED_STRING or values disallowed for
a particular name |
def magnum.
Construct from a 2D field view
| Exceptions | |
|---|---|
| AssertionError | If mapping_data and first dimension of
field_data don’t have the same size |
| AssertionError | If field_type is not valid for name |
| AssertionError | If field_type is a string type or
SceneFieldType.BIT |
| AssertionError | If mapping_data stride doesn’t fit into 16 bits |
| AssertionError | If mapping_data format size is smaller than
size of mapping_type |
| AssertionError | If field_data first dimension stride doesn’t
fit into 16 bits |
| AssertionError | If field_data second dimension isn’t contiguous |
| AssertionError | If field_data format size times second
dimension size is smaller than size of field_type at given field_array_size |
| AssertionError | If field_array_size is non-zero and name
can’t be an array field |
| AssertionError | If flags contain
SceneFieldFlags.OFFSET_ONLY,
SceneFieldFlags.NULL_TERMINATED_STRING or values disallowed for
a particular name |
def magnum.
Construct a bit field
| Exceptions | |
|---|---|
| AssertionError | If mapping_data and field_data don’t have
the same size |
| AssertionError | If SceneFieldType.BIT is not valid for
name |
| AssertionError | If mapping_data stride doesn’t fit into 16 bits |
| AssertionError | If mapping_data format size is smaller than
size of mapping_type |
| AssertionError | If field_data stride doesn’t fit into 16 bits |
| AssertionError | If flags contain
SceneFieldFlags.OFFSET_ONLY,
SceneFieldFlags.NULL_TERMINATED_STRING or values disallowed for
a particular name |
def magnum.
Construct an array bit field
| Exceptions | |
|---|---|
| AssertionError | If mapping_data and first dimension of
field_data don’t have the same size |
| AssertionError | If SceneFieldType.BIT is not valid for
name |
| AssertionError | If mapping_data stride doesn’t fit into 16 bits |
| AssertionError | If mapping_data format size is smaller than
size of mapping_type |
| AssertionError | If field_data first dimension stride doesn’t
fit into 16 bits |
| AssertionError | If field_data second dimension isn’t contiguous |
| AssertionError | If flags contain
SceneFieldFlags.OFFSET_ONLY,
SceneFieldFlags.NULL_TERMINATED_STRING or values disallowed for
a particular name |
Property documentation
magnum.
Field data
| Exceptions | |
|---|---|
| NotImplementedError | If field_type is a half-float or string type |
A containers.StridedArrayView2D
or containers.StridedBitArrayView2D
is returned always, non-array attributes have the second dimension size
1.