============================= ``grail.ms3d.element`` Module ============================= .. include:: ../../version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- Create and manipulate MineSightŪ elements via this module. Elements are the standard means of communicating data within the MineSightŪ-3D environment. ----------- Definitions ----------- Standard definitions for this module: **Points**: A list of co-ordinates, defined as: [x, y, z]. **Point Lists**: A list of points, defined as: [[x0, y0, z0], ..., [xN, yN, zN]]. **Planes**: A tuple of floats, defined as: (A, B, C, D) where A, B, C & D are the co-efficients of a plane equation **Face Lists**: All face lists are described such that the first index indicates how many faces are in the face. For example, [**3**, 1, 2, 3, **3**, 4, 5, 6] States that there are 3 vertexes in the first face, and those vertexes are 1, 2, 3. Then the next face contains 3 vertexes, which are 4, 5, 6. This may seem a bit confusing, but using this structure buys us some definite efficiencies. .. Note:: All faces in MineSightŪ products have 3 vertexes. **Matrix**: This is a list of lists. Each list will contain 4 elements of the form, [ [e00, e01, e02, e03], [e10, e11, e12, e13], [e20, e21, e22, e23], [e30, e31, e32, e33] ] A modeling matrix, which indicates the transformation applied to a label starting at point P. The transformation matrix typically has rotation and translation data stored in it. Consult a Graphics Programming book for more information on transformation matrices. All matrices are right-multiplied. The standard is shown in the book *Computer Graphics* by Foley [#foley]_. **Vectors**: A list of x, y, and z components, defined as [x, y, z]. **Orientation Vector**: Used to specify the position and orientation of a text element (for example with semi/non-transform labels). The Orientation Vector is comprised of three points: the origin, an up vector, and a right vector. As in, .. Python:: [[Xo, Yo, Zo], [Xu, Yu, Zu], [Xr, Yr, Zr]] where "o" implies origin, "u" implies up vector, and "r" implies right vector. The up and right vectors are specified as unit vectors that generate a triangle. The following diagram helps to explain, .. figure:: orientation-vector.gif :alt: Picture of an orientation vector. Picture of an orientation vector. In most cases if you only supply a single point, as in, .. Python:: [Xo, Yo, Zo] a default up and right vector will be provide for you. ------------- Element Class ------------- class :dc:`Element` An :c:`Element` object defines one of the possible geometry types that can be found within MS-3D. Whenever you create shell (surface/solid), polyline, polygon or marker, you will get :c:`Element` as a return value. Typically Geometry MSR files consist of a collection of :c:`Elements`. :df:`get_pointlist()` Returns a list of points that define the element (see `Point List` in Definitions_). The values within the point list are with respect to the project's coordinates. If you wish to get the raw point values you will need to subtract the projects x, y and z minimum values (see :f:`get_xmin`, :f:`get_ymin` and :f:`get_zmin` in grail.ms3d.project_). If the :c:`Element` is a :d:`element.NonTransformLabelType` (upright label) or :d:`element.SemiTransformLabelType` (forward label), then this will return the list of points corresponding to the label's location, up vector and right vector. :df:`get_facelist()` Returns a facelist that defines the element (see Face Lists in Definitions_). This is only applicable for :d:`element.ShellType` elements. All other elements will return an empty list (:a:`[]`). :df:`get_label_alignment_block()` Returns the label text block alignment around the insertion point. Call is_label_alignment_block_set() first to see if there is a block alignment set on the label. The return value if not set is meaningless. This will return one of the following values. .. Python:: Element.LABEL_ALIGNMENT_BLOCK_TOP_LEFT, Element.LABEL_ALIGNMENT_BLOCK_TOP_CENTER, Element.LABEL_ALIGNMENT_BLOCK_TOP_RIGHT, Element.LABEL_ALIGNMENT_BLOCK_MID_LEFT, Element.LABEL_ALIGNMENT_BLOCK_MID_CENTER, Element.LABEL_ALIGNMENT_BLOCK_MID_RIGHT, Element.LABEL_ALIGNMENT_BLOCK_BOT_LEFT, Element.LABEL_ALIGNMENT_BLOCK_BOT_CENTER, Element.LABEL_ALIGNMENT_BLOCK_BOT_RIGHT :df:`get_label_alignment_line()` Returns the label line alignment. The longest line in a label defines the label block width. All other, shorter lines will adjust left, center, or right based on this longest line. This will return one of the following values. .. Python:: Element.LABEL_ALIGNMENT_LINE_LEFT, Element.LABEL_ALIGNMENT_LINE_CENTER, Element.LABEL_ALIGNMENT_LINE_RIGHT :df:`get_label_color_[r|g|b]()` Returns the label color. Call is_label_color_set() first to see if there is a color set on the label. The return value if not set is meaningless. Values are between 0.0 and 1.0. :df:`get_label_font()` Returns the label font. Call is_label_font_set() first to see if there is a font definition set on the label. The return value if not set is meaningless. :df:`get_label_size()` Returns the font size of the label. Call is_label_size_set() to see if there is a size set on the label. The return value if not set is meaningless. Call is_label_size_relative() to determine if the value returned is a percent value from 0.0 to 100.0 or a project unit value. :df:`get_label_spacing()` Returns the character spacing of the label. This will return one of the following values. .. Python:: Element.LABEL_SPACING_PROPORTIONAL, Element.LABEL_SPACING_MONOSPACE, Element.LABEL_SPACING_MONOSPACE_NUMBER :df:`get_label_text()` Returns the text of the label as a single string. Multi-line text labels will have embedded new line characters inside the string. :df:`get_label_type()` Returns the type of label. This will return one of the following values. Element.LABEL_TYPE_FIXED, Element.LABEL_TYPE_FORWARD, Element.LABEL_TYPE_UPRIGHT :df:`get_material()` Returns the name of the material associated with this :c:`Element` as a string. A blank string, "", indicates that no material is associated with this element. :df:`get_name()` Returns the name of the element as a string. :df:`get_parent_name()` Returns the name of the MineSightŪ Resource (MSR) file that this element belongs too. For example, if you loaded a shell from a datamanager object found at :file:`\\myfolder\\myshellobject`, then this function will return, .. Python:: myshellobject If this element has not been "rooted" into a MSR file yet, this method will return a blank string (""). :df:`get_parent_path()` Returns the path relative to the datamanager for the MSR file. The path will lack the MSR extension. For example, if you loaded a shell from a datamanager object found at :file:`\\myfolder\\myshellobject`, then this function will return, .. Python:: \\myfolder\\myshellobject If this element has not been "rooted" into a MSR file yet, this method will return a blank string (""). :df:`get_parent_physical_path()` Returns the physical path to the MineSightŪ Resource (MSR) file on the disk. For example, if you Resource directory was at :file:`c:\\myproject\\_msresource`, and you loaded a shell from a datamanager object found at :file:`\\myfolder\\myshellobject`, then this function will return, .. Python:: c:\\myproject\\_msresource\\myfolder\\myshellobject.msr :df:`get_plane()` Returns the plane of an element. If this element is non planar, or has no plane will return None. :df:`get_text()` Returns the text. Each line is delimited with a "\\n". If this :c:`Element` is not an type of label, then this will return a blank string. :df:`get_type()` Returns the type of the element. All types are defined in the Data_ section and are typically named as :d:`element.Type`. For example a polygon would be a :d:`element.PolygonType`. :df:`is_label_alignment_block_set()` Returns :d:`True` if the block alignment is set per label. :d:`False` otherwise. :df:`is_label_color_set()` Returns :d:`True` if the coloer is set per label. :d:`False` otherwise. :df:`is_label_fixed_and_locked()` Returns :d:`True` only if the label is of fixed type and is locked. Locked means that the label will not flip if viewed from behind or upside down. False is returned otherwise. :df:`is_label_font_bold()` Returns :d:`True` if the font is bold. :d:`False` otherwise. Call is_label_font_set() to see if there is a font set on the label. The return value if not set is meaningless. :df:`is_label_font_italic()` Returns :d:`True` if the font is italic. :d:`False` otherwise. Call is_label_font_set() to see if there is a font set on the label. The return value if not set is meaningless. :df:`is_label_font_set()` Returns :d:`True` if the font is set per label. :d:`False` otherwise. :df:`is_label_size_relative()` Returns :d:`True` if the font size is a 5 size of the screen. :d:`False` if the size in project units. Call is_label_size_set() to see if there is a size set on the label. The return value if not set is meaningless. :df:`is_label_size_set()` Returns :d:`True` if the size is set per label. :d:`False` otherwise. :df:`is_parent()` Returns :d:`True` if this element belongs to a MineSightŪ Resource (MSR) file. In otherwords, the element was not created, it was rooted in an original file. :df:`set_label_alignment_block(set [, alignment])` Set a per label block :a:`alignment`. Block alignment is where the origin point for the label is positioned with respect to the text block of the label. :a:`set` should be :d:`True` to set the size. :d:`False` to remove the setting. :a:`alignment` is one of the following. .. Python:: Element.LABEL_ALIGNMENT_BLOCK_TOP_LEFT, Element.LABEL_ALIGNMENT_BLOCK_TOP_CENTER, Element.LABEL_ALIGNMENT_BLOCK_TOP_RIGHT, Element.LABEL_ALIGNMENT_BLOCK_MID_LEFT, Element.LABEL_ALIGNMENT_BLOCK_MID_CENTER, Element.LABEL_ALIGNMENT_BLOCK_MID_RIGHT, Element.LABEL_ALIGNMENT_BLOCK_BOT_LEFT, Element.LABEL_ALIGNMENT_BLOCK_BOT_CENTER, Element.LABEL_ALIGNMENT_BLOCK_BOT_RIGHT Returns :d:`True` on success. :d:`False` otherwise. :df:`set_label_alignment_line(alignment)` Set a label line :a:`alignment`. Line alignment is how each line in the label is position with respect to the longest line in the label text block. :a:`alignment` is one of the following. .. Python:: Element.LABEL_ALIGNMENT_LINE_LEFT, Element.LABEL_ALIGNMENT_LINE_CENTER, Element.LABEL_ALIGNMENT_LINE_RIGHT Returns :d:`True` on success. :d:`False` otherwise. :df:`set_label_color(set [, r, g, b])`: Set a per label color. :a:`r`, :a:`g`, and :a:`b` must be numbers between 0.0 and 1.0 (inclusive). :a:`set` should be :d:`True` to set the size. :d:`False` to remove the setting. Returns :d:`True` on success. :d:`False` otherwise. :df:`set_label_font(set [, fontName, isBold, isItalic])` Set a per label font. :a:`set` should be :d:`True` to set the size. :d:`False` to remove the setting. :a:`fontName` is the name of the font you will find in the font picker in MineSight. If it is misspelt or can not be found then this operation will return :d:`False` and do nothing. :a:`isBold` and :a:`isItalic` will indicate how the font should be rendered. Note, not all fonts have a bold representation. Returns :d:`True` on success. :d:`False` otherwise. :df:`set_label_size(set [, size, isRelative])` Set a per label size. :a:`set` should be :d:`True` to set the size. :d:`False` to remove the setting. :a:`size` should be larger than 0.0. :a:`isRelative` will indication that the provided size is a percent value. Returns :d:`True` on success. :d:`False` otherwise. :df:`set_label_spacing(spacing)` Set the label character spacing. :a:`spacing` is one of the following. .. Python:: Element.LABEL_SPACING_PROPORTIONAL, Element.LABEL_SPACING_MONOSPACE, Element.LABEL_SPACING_MONOSPACE_NUMBER Monospace will space the letters such that the widest letter also fits in the space provided. Monospace Number will space the letters based on the widest number character. If you asked to print a 'W' using this option, the W may overlap neighboring characters as there may not be enough space. Returns :d:`True` on success. :d:`False` otherwise. :df:`set_label_type(type)` Set the label type. :a:`type` is one of the following. .. Python:: Element.LABEL_TYPE_FIXED, Element.LABEL_TYPE_FORWARD, Element.LABEL_TYPE_UPRIGHT Returns :d:`True` on success. :d:`False` otherwise. :df:`set_label_type_locked(value)` Set a FIXED label to be also locked. This means the label will not flip the rendering of the text when viewed upside down or from behind. This function will fail if the label type is not set to FIXED. Returns :d:`True` on success. :d:`False` otherwise. :df:`set_material(materialName [,create_if_not_exist])`: Sets a :a:`materialName` for the :c:`Element`, where the :a:`materialName` is a material defined within the project's :file:`materials` folder. If the material does not exist in the project's :file:`material` folder this function will generate an :e:`IOError` by default. If you set the :a:`create_if_not_exist` to 1, then this function will create a new material object within the project. For example, to set a material on an object, and have that material be created if it does not already exist you can do the following, .. Python:: el.set_material("SampleMaterial", create_if_not_exist=1) Now your :c:`Element` will have a "SampleMaterial" associated with it, as well as, the project will have a new "SampleMaterial" added to it. .. Warning:: If your element does not have a name, the :f:`set_material` function will generate a :e:`IOError`. Any :c:`Element` object that lacks a name can not have a material. In order to avoid the potential error, you can use the :f:`set_name_and_material` to set a name and material in one step. :df:`set_name(name)` Sets a new name on the element. :df:`set_name_and_material(name, material [,create_if_not_exist])` Sets the :a:`name` and :a:`material` on an object in one step. With an :c:`Element` object you need to specify a name in order to set a material, this convience function lets you do it in one step. If the material does not exist in the project's :file:`material` folder this function will generate an :e:`IOError` by default. If you set the :a:`create_if_not_exist` to 1, then this function will create a new material object within the project. In cases where you want to just use the existing name and continue to take advantage of this method, you can do the following, .. Python:: el.set_name_and_material(el.get_name(), "SampleMaterial") See also :f:`set_material`. :df:`set_plane(plane)` Takes a single arguement plane, if plane is True will calculate and set the plane of the element (if no plane can be calculated element will remain 3D). If plane is False will set the element to 3D. Only works with polylines and polygons. --------- Functions --------- :df:`generate_shape(shapetype, height, width, depth, rotation, position)` Generates a shape based on the shapetype and specified dimensions. All Shapes are defined in this module and are prefixed with :d:`SHAPE_`. For example, the dump truck shape is defined as, :d:`element.SHAPE_DUMP_TRUCK`. Arguments: :a:`shapetype` : constant (see Data_) Type of shape, one of the :d:`element.SHAPE_` constants. :a:`height` : float Height for your shape. This corresponds to the Z direction, and is equivalent to the project's elevation. :a:`width` : float Width for your shape. This corresponds to the X direction, and is equivalent to the project's easting. :a:`depth` : float Depth for your shape. This corresponds to the Y direction, and is equivalent to the project's northing. :a:`rotation` : float Rotation of the returned object in degrees. :a:`position` : list Starting position for your shape defined by a point (see Definitions_). Returns: A new :c:`Element` object with the defined shape (see `Element class`_). :df:`create_marker(point [,name])` Generates a new marker element of type element.MarkerType. Argument: :a:`point` : list A location for the new marker (see Definitions_). :a:`name` : string An element name. Returns: A new :c:`Element` object with the defined shape (see `Element class`_). :df:`create_label(orientationVector, text [, name])` Creates a label at the given :a:`position`. Arguments: :a:`orientationVector` : list of points Position of the label defined by a point (see Orientation Vectors in Definitions_). :a:`text` : list or string This is either a list of strings where each element in the list corresponds to a line on the non-transform label, or a string with a "\\n" delimiter to represent a line. :a:`name` : string An element name. :df:`create_nontransform_label(orientationVector, text [, name])` Creates a non-transform label at the given :a:`position`. Arguments: :a:`orientationVector` : list of points Position of the label defined by a point (see Orientation Vectors in Definitions_). In earlier versions of this function you could just supply a single point and a default up and right vector would be supplied for you. This behaviour is still available. :a:`text` : list or string This is either a list of strings where each element in the list corresponds to a line on the non-transform label, or a string with a "\\n" delimiter to represent a line. :a:`name` : string An element name. .. Warning:: DEPRECATED (as of MineSightŪ v8.00) Use create_label() instead. This funtion will still work so old scripts will continue to run. :df:`create_polygon(pointlist [,name, is_planar])` Create a polygon element. If the last point on the polygon is not the same as the first, it will be duplicated upon creation. The difference between a polygon and a polyline is that a polygon is a closed segment. Argument: :a:`pointlist` : list A list of points (see Definitions_). :a:`name` : string An element name. :a:`is_planar` : int Anything other than 0 will make the element planar, defaults to 0 Returns: A new :c:`Element` object with the defined shape (see `Element class`_). :df:`create_polyline(pointlist [,name, is_planar])` Creates a polyline element. Arguments: :a:`pointlist` : list A list of points (see Definitions_). :a:`name` : string An element name. :a:`is_planar` : int Anything other than 0 will make the element planar, defaults to 0 Returns: A new :c:`Element` object with the defined shape (see `Element class`_). :df:`create_semitransform_label(orientationVector, text [, name])` Creates a semi-transform label at the given :a:`position`. Arguments: :a:`orientationVector` : list of points Position of the label defined by a point (see Orientation Vectors in Definitions_). :a:`text` : list or string This is either a list of strings where each element in the list corresponds to a line on the semitransform label, or a string with a "\\n" delimiter to represent a line. :a:`name` : string An element name. .. Warning:: DEPRECATED (as of MineSightŪ v8.00) Use create_label() instead. This funtion will still work so old scripts will continue to run. :df:`create_transform_label(position, matrix, text[, name])` Creates a transform label at the given at the :a:`position`. Arguments: :a:`position` : list A Point as defined in the Definitions_ section. :a:`matrix` : list of lists A Matrix as defined in the Definitions_ section. :a:`text` : string This is a string representing the text you wish to display. For multi-line text use the :a:`\n` within the string. For example, .. Python:: multiLine = "Line1\nLine2" :a:`name` : string (Optional) name of the element. .. Warning:: DEPRECATED (as of MineSightŪ v8.00) Use create_label() instead. This funtion will still work so old scripts will continue to run. :df:`create_shell(pointlist, facelist[,name])` Creates a shell (surface or solid) defined by the point list and face list. Point list and face list is as defined in grail.ag. Arguments: :a:`pointlist` : list A list of points (see Definitions_). :a:`facelist` : list A list of faces using the 'hoops' convention (see Definitions_). :a:`name` : string An element name. Returns: A new :c:`Element` object with the defined shape (see `Element class`_). :df:`is_element(object)` Returns :d:`True` if the supplied :a:`object` is an :c:`Element` class. ---- Data ---- :dd:`DEFAULT_NAME` Default name for all elements. :dd:`SHAPE_CUBOID` Signals you want a cuboid shape. :dd:`SHAPE_CONE` Signals you want a cone shape. :dd:`SHAPE_SPHERE` Signals you want a sphere shape. :dd:`SHAPE_CONIFEROUS_TREE` Signals you want a coniferous tree shape. :dd:`SHAPE_DECIDUOUS_TREE` Signals you want a deciduous tree shape. :dd:`SHAPE_HEAD_FRAME` Signals you want a head frame shape. :dd:`SHAPE_DRILL_RIG` Signals you want a drill rig shape. :dd:`SHAPE_DUMP_TRUCK` Signals you want a dump-truck shape. :dd:`SHAPE_FULL_DUMP_TRUCK` Signals you want a full dump-truck shape. :dd:`SHAPE_SCOOP` Signals you want a scooper shape. :dd:`SHAPE_SHOVEL` Signals you want a shovel shape. :dd:`SHAPE_EXCAVATOR` Signals you want an excavator shape. :dd:`SHAPE_DIGGER` Signals you want a digger shape. :dd:`SHAPE_DRAGLINE` Signals you want drag line shape. :dd:`SHAPE_BUCKET_WHEEL` Signals you want a bucket wheel shape. :dd:`SHAPE_DRILL` Signals you want a drill shape. :dd:`SHAPE_ROCK_BOLTER` Signals you want a rock bolter shape. :dd:`SHAPE_MINER` Signals you want a miner shape. :dd:`NoType` Elements that have no type defined for them. :dd:`MarkerType` Elements that are markers. :dd:`PolylineType` Elements that are polylines. :dd:`PolygonType` Elements that are polygons. :dd:`ShellType` Elements that are shells. This defines all surfaces and solids within MineSightŪ 3D. :dd:`MeshType` Elements that are meshes. :dd:`GridType` Elements that are grids. :dd:`TextType` Elements that are text. .. Warning:: DEPRECATED (as of MineSightŪ v3.50-04). Prefer to use the exact 'Label' type instead (i.e. :d:`SemiTransformLabelType`, also known as a Forward Label). :dd:`SemiTransformLabelType` Elements that are semi-transform labels. These are also known as "Forward Labels". :dd:`NonTransformLabelType` Elements that are non-transform labels. These are also known as "Upright Labels". :dd:`SpecialElementType` Special elements (very rare). :dd:`TransformLabelType` Elements that are transform labels. These are known as "Fixed Labels". --------- Reference --------- .. [#foley] Foley, James D., et al. *Computer Graphics: Principles and Practice in C*. 2nd Edition. Boston: Addison Wesley, 1995.