alias_api.AlSurface
- class alias_api.AlSurface
Bases:
AlObjectInterface to Alias nurbs surface geometry.
AlSurface is the interface to the geometric data of Alias’ NURBS surface objects. To create a surface, first instantiate and create an AlSurface and then instantiate and create an AlSurfaceNode. There is only a limited amount that you can do with an AlSurface that does not have an AlSurfaceNode.
For more information on how to create the surface geometry, see the description for the create() method.
The method is_construction_history_resulting_surface() is used to find out if a surface may be modified based on changes to its constructor objects.
A NURBS surface is described as having two dimensions u and v. Many of the surface properties (form, multiplicity, etc.) are the same as a NURBS curve but are expressed in both the u and v direction.
The form of a surface in the u or v direction can be one of three types: periodic, closed or open. If a surface is “kPeriodic” in u, then it is tangent continuous in u at all points in that direction. If a surface is “Closed” in u, it is not periodic but its edges in the u direction are coincident. If the surface is neither closed nor periodic in u, it is considered to be “Open”. The same applies in the v direction.
There are two ways to delete an AlSurface. If the AlSurface delete_object() is called, the attached AlSurfaceNode is deleted. If the AlSurfaceNode delete_object() is called, the attached AlSurface is deleted.
You should always create a surface node for a surface. If you create a surface with no surface node, then the surface is not added to the universe. If you should lose the pointer to the the surface, it will become lost memory.
There is one limitation to this class: you cannot add or remove individual CV’s (except by changing multiplicity).
If an AlSurface has curves-on-surface, then you can get a pointer to the first curve-on-surface and then traverse the curves using methods in the class AlCurveOnSurface.
If an AlSurface is trimmed, the trim regions on the surface can be accessed using the first_trim_region() method and then traversed using methods in the class AlTrimRegion.
All AlSurface objects will have at least one shader attached to them. These can be accessed through the first_shader() and next_shader() methods.
All AlSurface objects have render information attached to them. The AlRenderInfo structure can be used to query the surface’s render parameters.
Surfaces are made of surface control points (or CV’s) which you traverse as a list by using the first_cv() in conjunction with the AlSurfaceCV methods. You can also pack the surface information into an array using methods in this class.
What is multiplicity?
An AlSurfaceCV object can actually represent multiple CV’s, depending on the AlSurfaceCV’s multiplicity and periodicity. Notice that in this class there are two sets of methods - some “incl_multiples” and some not (namely “number_of_cvs”, “cvs_world_position”, “cvs_unaffected_position”, etc). The set of methods without multiplicity lets you get all surface CV’s where a surface CV can have multiplicity of 1, 2 or 3. The set of methods “incl_multiples” lets you get ALL surface CV’s including multiples due to a multiplicity > 1 and due to periodicity.
Example 1:
Create a surface in the interactive Alias package with 16 CV’s, and pick the CV which is 2nd in the u direction and 2nd in the v direction. Set the multiplicity of this CV to 3 in the u direction and 2 in the v direction (using the “multiplicity” menu item in the Curve Tools menu). Then:
number_of_cvs() will return 4. number_of_cvs() will return 4.
cvs_world_position must be passed a 4x4x4 CVs matrix, and the u and v multiplicity vectors must each be of length 4.
cvs_unaffected_position() must be passed the same as item 2.
set_cvs_unaffected_position() must be passed the same as item 2.
number_of_cvs_incl_multiples() will return 6. number_of_cvs_incl_multiples() will return 5.
cvs_world_position_incl_multiples() must be passed a 6x5x4 CVs matrix.
You will notice that in this matrix there are duplicate CVs to indicate multiples due to mutiplicity > 1 and periodicity.
cvs_unaffected_position_incl_multiples() must be passed the same as item 6.
You will notice that in this matrix there are duplicate CVs to indicate multiples due to mutiplicity > 1 and periodicity.
set_cvs_unaffected_position_incl_multiples() must be passed the
same as item 6. Similar to items 6 and 7, you should put duplicate CVs to account for multiples although this is not mandatory. You may want to refer to the examples in the AlCurve class description. The way CVs are ignored also applies to this method.
Example 2:
If you create a surface in the interactive Alias package with 16 CV’s and “close” the surface in the u direction (using the “close” menu item in the Object Tools menu), you create a periodic surface. Then:
number_of_cvs() will return 4. number_of_cvs() will return 4.
2. cvs_world_position must be passed a 4x4x4 CVs matrix, and the u and v multiplicity vectors must each be of length 4. 3. cvs_unaffected_position() must be passed the same as item 2. 4. set_cvs_unaffected_position() must be passed the same as item 2. 5. number_of_cvs_incl_multiples() will return 7. number_of_cvs_incl_multiples() will return 4. 6. cvs_world_position_incl_multiples() must be passed a 7x4x4 CVs matrix. 7. cvs_unaffected_position_incl_multiples() must be passed the same as item 6. 8. set_cvs_unaffected_position_incl_multiples() must be passed the same as item 6. Similar to items 6 and 7, you should put duplicate CVs to account for multiples although this is not mandatory. You may want to refer to the examples in the AlCurve class description. The way CVs are ignored also applies to this method.
How do I process a matrix of CV’s?
Methods in this class store CV’s in the V direction first, then in the U direction. Here’s an example of how to get the world positions of the CV’s of a surface and print them out in V direction then U direction. (Notice that the outer “for” loop uses the number of CV’s in the U direction).
- assign_shader(self: alias_api.AlSurface, shader: AlShader) int
Assign the given shader to the surface.
If the surface already has shaders they will be removed from the surface. The surface must have a surface node for this method to succeed.
- Parameters
shader (AlShader) – The shader which will be assigned to the surface.
- Returns
The status code result Success - the shader was successfully assigned to the surface. InvalidArgument - ‘shader’ was invalid Failure - the shader was not created. InvalidObject - the surface is invalid
- Return type
int(AlStatusCode)
- assign_switch_shader(self: alias_api.AlSurface, shader: AlSwitchShader) int
Assign the given switch shader to the surface.
If the surface already has shaders they will be removed from the surface. The surface must have a surface node for this method to succeed.
- Parameters
shader (AlSwitchShader) – The switch shader which will be assigned to the surface.
- Returns
The status code result Success - the shader was successfully assigned to the surface. InvalidArgument - ‘shader’ was invalid Failure - the shader was not created. InvalidObject - the surface is invalid
- Return type
int(AlStatusCode)
- copy_wrapper(self: alias_api.AlSurface) alias_api.AlObject
Return an exact duplicate of this AlSurface wrapper.
- create_sphere(self: alias_api.AlSurface, center: alPyMath::Vec3, radius: typing.SupportsFloat) int
Create a spherical surface from an origin point and a radius.
- delete_object(self: alias_api.AlSurface) int
Delete the AlSurface from the Alias Universe and return the status of the performed operation.
- first_shader(self: alias_api.AlSurface) AlShader
Return the first shader that this surface object references. Return None if there are no shaders.
- get_curves_on_surface(self: alias_api.AlSurface) list[alias_api.AlCurveOnSurface]
Return a list of curve on surface nodes.
- get_layered_shader(self: alias_api.AlSurface) AlLayeredShader
Return the attached layered shader.
- get_shaders(self: alias_api.AlSurface) list[AlShader]
Return a list of shaders.
- get_switch_shader(self: alias_api.AlSurface) AlSwitchShader
Return the attached switch shader.
- is_construction_history_resulting_surface(self: alias_api.AlSurface) int
Returns True if this surface is the resulting surface of a construction history operation, else False.
- layer_shader(self: alias_api.AlSurface, shader: AlShader) int
Layers the given shader on the surface.
The surface must have a surface node for this method to succeed.
- Parameters
shader – the shader which will be layered on the surface.
- Tye shader
AlShader
- Returns
The status code result Success - the shader was successfully layered on the surface. InvalidArgument - ‘shader’ was invalid Failure - the shader was not created. InvalidObject - the surface is invalid
- Return type
int(AlStatusCode)
- property name
Get or set the AlSurface name.
- next_shader(self: alias_api.AlSurface, shader: AlShader) AlShader
Return the shader after the given shader in the object’s shader list.
Return None if there isn’t a next shader. Specifying None as parameter will return the first shader.
- surface_node(self: alias_api.AlSurface) AlSurfaceNode
Return the surface node for this surface. Return None if there is no surface node attached.
- type(self: alias_api.AlSurface) alias_api.AlObjectType
Return the AlSurface type identifier.