Model Researcher API
This page describes all the functions of the API 3D Model Researcher. Python 3.6 is used as the scripting language. All the main functions for interacting with the program are in the module mrp, so any script, if it is supposed to access the program through the API, should start with the line
import mrp
MRP
- mrp.get_bfile()
- mrp.create_mesh()
- mrp.remove_mesh()
- mrp.get_mesh()
- mrp.render()
- mrp.print_mesh()
- mrp.view_uvs()
- mrp.create_material()
mrp.get_bfile¶
- mrp.get_bfile(byte_order = "<")
-
Retrieves the BufferFile object with the file open in the program in the "rb" mode.
Parameters: byte_order : str
The byte order is specified in which the file will be read using the methods of the BufferFile object. It can take two values:
"<" – reverse order (Little Endian);
">" – direct order (Big Endian);Returns: Object BufferFile
mrp.create_mesh¶
- mrp.create_mesh(name = "Root")
-
A mesh is created and added to the list. If the mesh with the specified name already exists, it is returned.
Parameters: name : str
The name of the created mesh. Invalid names: "Root", "All", " ", "".
Returns: Object Mesh
mrp.remove_mesh¶
- mrp.remove_mesh(name)
-
Removes the mesh.
Parameters: name : str
The name of the removed mesh.
mrp.get_mesh¶
- mrp.get_mesh(name = "Root", clear = False)
-
Retrieves the mesh.
Parameters: name : str
The name of retrieved mesh.
clear : bool
If True, then the function will clean the mesh before retrieving.
Returns: Object Mesh
mrp.render¶
- mrp.render(name = "Root")
-
Render one mesh or multiple in the 3D View tab.
Parameters: name : str or tuple or list
The name parameter takes the name of the mesh which is to be rendered. If you send "All", then the program will try to render all the meshes. To render certain meshes as a name argument, you can pass a list or a tuple with mesh names. For example: ("Mesh1", "Head", "Mesh8").
mrp.print_mesh¶
- mrp.print_mesh(name = "Root")
-
Displays the mesh data in text form in the Text tab.
Parameters: name : str
The name of the mesh which is to be displayed.
mrp.view_uvs¶
- mrp.view_uvs(name = "Root")
-
Outputs the texture coordinates of the mesh in a graphical form in the Texture tab.
Parameters: name : str
The name of the mesh which is to be displayed.
mrp.create_material¶
- mrp.create_material(name = "Default")
-
Creates and retrieves material.
Parameters: name : str
The name of the material.
Returns: Object Material
Object Mesh
- Mesh.set_vertices()
- Mesh.swap_vertices()
- Mesh.set_faces()
- Mesh.swap_faces()
- Mesh.set_uvs()
- Mesh.swap_uvs()
- Mesh.set_uvs_indices()
- Mesh.swap_uvs_indices()
- Mesh.set_normals()
- Mesh.swap_normals()
- Mesh.set_normals_indices()
- Mesh.swap_normals_indices()
- Mesh.set_color()
- Mesh.set_color_hsv()
- Mesh.set_material()
- Mesh.set_material_faces()
Mesh.set_vertices¶
- Mesh.set_vertices(vertices, fm="XYZ", inv="", tp="Float")
-
Assigns the passed vertices to the mesh.
Parameters: vertices : tuple or list or bytes
Vertex data. Accepts a matrix - a list or tuple of lists or tuples with three numeric values of x, y, z. It can also take a string of bytes, the size of which must be a multiple of 3 and of the data type size (for example, Half-Float – 2 bytes).
fm : str
Specifies to which format to convert the data. The argument may take the following values: "XYZ", "XZY", "YXZ", "YZX", "ZXY", "ZYX".
inv : str
Specifies which coordinates to invert. The coordinates are indicated in a single line in lowercase. For example, "xz".
tp : str
Specifies the data type of the transmitted vertices. It may take the following values: "Float", "Half-Float" (or "HF"), "Integer", "Short", "Short_signed", "Byte". If a list or tuple is passed as the vertices argument, the tp parameter can take only one value – "Short_signed", and the data will be converted: there will be a division of coordinates by 256. The same transformations can be obtained using the Mesh.swap_vertices() method.
Example
# Transmission of the list with tuples vertices = [(-20, 50.0 , 45), (17.34, 77.5, 33)] mesh = mrp.get_mesh() mesh.set_vertices(vertices) # Byte transfer (2 vertices, Half-Float type) vertices = b'\xa8T\xa4P\xc9U$Q\xd6KvU' mesh = mrp.get_mesh() mesh.set_vertices(vertices, tp="HF")
Mesh.swap_vertices¶
- Mesh.swap_vertices(fm="XYZ", inv="", tp="")
-
Transforms the vertices of the mesh.
Parameters: fm : str
Specifies the conversion format. The parameter may take the following values: "XYZ", "XZY", "YXZ", "YZX", "ZXY", "ZYX".
inv : str
Specifies which coordinates to invert. The coordinates are indicated in a single line in lowercase. For example, "xz".
tp : str
Specifies the type of vertex data which are to be converted. Takes only one value, "short_signed," and the data will be converted in the following way: there will be a division of coordinates by 256.
Example
# Change the Y and Z coordinates and invert the X coordinate vertices = [(-20, 50.0 , 45), (17.34, 77.5, 33)] mesh = mrp.get_mesh() mesh.set_vertices(vertices) mesh.swap_vertices("XZY", "x")
Mesh.set_faces¶
- Mesh.set_faces(faces, fm="Triangles", tp="Short")
-
Assign the transferred faces to the mesh.
Parameters: faces : tuple or list or bytes
The face data. Accepts a matrix – a list or tuple of lists or tuples with three non-negative numeric value of the face indices. It can also accept a simple array (list or tuple) with nonnegative numeric values, while the parameter fm must be different from "Triangles". In addition, it can take a string of bytes, the size of which must be a multiple of 3 and of the data type size (for example, short – 2 bytes). The multiplicity condition is optional when the parameter fm is different from "Triangles".
fm : str
Specifies the format in which the data is transmitted. The argument may take the following values: "Triangles", "TStrip", "TStripFF". TStrip – Triangle Strip TStripFF – Triangle Strip with division 0xFFFF or 0xFFFFFFFF.
tp : str
Specifies the data type of the transmitted faces. It may take the following values: "Integer", "Short", "Byte". The parameter should be specified in two cases:
1) The parameter fm is different from "Triangles".
2) A byte string is passed as the faces argument.Example
# Transmission of the list with tuples faces = [(0, 1 , 2), (2, 0, 3)] mesh = mrp.get_mesh() mesh.set_faces (faces) # Byte transmission (2 faces, type – Short) faces = b'\x00\x00\x01\x00\x02\x00\x02\x00\x00\x00\x03\x00' mesh = mrp.get_mesh() mesh.set_faces(faces, tp="Short")
Mesh.swap_faces¶
- Mesh.swap_faces(fm="Triangles", tp="Short")
-
Transforms the faces of the mesh.
Parameters: fm : str
The format of the conversion. The argument may take the following values: "Triangles", "TStrip", "TStripFF". TStrip – Triangle Strip TStripFF – Triangle Strip with division 0xFFFF.
tp : str
The data type. It may take the following values: "Integer", "Short", "Byte".
Mesh.set_uvs¶
- Mesh.set_uvs(uvs, fm="UV", tp="Float")
-
Assigns the transferred texture coordinates to the mesh.
Parameters: uvs : tuple or list or bytes
Textures data. Accepts a matrix – a list or tuple of lists or tuples with two numeric values of u, v. It can also take a string of bytes, the size of which must be a multiple of 2 and of the data type size (for example, Half-Float – 2 bytes).
fm : str
Specifies to which format to convert the data. The argument may take the following values: "UV", "VU".
tp : str
Specifies the data type of the transferred texture coordinates. It may take the following values: "Float", "Half-Float" (or "HF"), "Integer", "Short", "Short_signed", "Byte". If a list or tuple is passed as the uvs argument, the tp parameter can take only one value – "Short_signed", and the data will be converted: division of coordinates will be performed. The same transformation can be made using the Mesh.swap_uvs() method.
Example
# Transmission of the list with tuples uvs = [(0.75, 0.25), (0.5, 0.18)] mesh = mrp.get_mesh() mesh.set_uvs(uvs)
Mesh.swap_uvs¶
- Mesh.swap_uvs(fm="UV", tp="")
-
Transforms the vertices of the mesh.
Parameters: fm : str
Specifies the conversion format. The parameter may take the following values: "UV", "VU".
tp : str
Specifies the type of texture coordinate which are to be converted. Takes only one value – "Short_signed".
Example
# Change of U and V the coordinates uvs = [(0.75, 0.25), (0.5, 0.18)] mesh = mrp.get_mesh() mesh.set_uvs(uvs) mesh.swap_uvs("VU")
Mesh.set_uvs_indices¶
- Mesh.set_uvs_indices(uvsi, fm="Triangles", tp="Short")
-
Assigns the transferred texture coordinate indices to the mesh.
Parameters: uvsi : tuple or list or bytes
The index data of the texture coordinates.
fm : str
Specifies the format in which the data is transmitted.
tp : str
Specifies the data type of the transferred texture coordinates.
Example
# Transmission of the list with tuples uvsi = [(0, 1, 2), (2, 0, 3)] mesh = mrp.get_mesh() mesh.set_uvs_indices(uvsi)
Mesh.swap_uvs_indices¶
- Mesh.swap_uvs_indices(fm="Triangles", tp="Short")
-
Converts texture coordinate indices of mesh if they have been passed.
Parameters: fm : str
The format of the conversion. The argument may take the following values: "Triangles", "TStrip", "TStripFF". TStrip – Triangle Strip TStripFF – Triangle Strip with division 0xFFFF.
tp : str
The data type. It may take the following values: "Integer", "Short", "Byte".
Mesh.set_normals¶
- Mesh.set_normals(normals, fm="XYZ", inv="", tp="Float")
-
Assigns the normal vectors to the mesh.
Parameters: normals : tuple or list or bytes
Normals vector data.
fm : str
Specifies to which format to convert the data.
inv : str
Specifies which coordinates to invert.
tp : str
Specifies the data type of the transmitted normal vectors.
Example
# Transmission of the list with tuples normals = [(0.0421, -0.1504, 0.9877), (0.1007, -0.0276, 0.9945)] normals = mrp.get_mesh() mesh.set_normals(normals)
Mesh.swap_normals¶
- Mesh.swap_normals(fm="XYZ", inv="", tp="")
-
Converts the normal vectors of the mesh.
Parameters: fm : str
Specifies the conversion format.
inv : str
Specifies which coordinates to invert.
tp : str
Specifies the type of vertex data which are to be converted.
Example
# Change the Y and Z coordinates and invert the X coordinate normals = [(0.0421, -0.1504, 0.9877), (0.1007, -0.0276, 0.9945)] normals = mrp.get_mesh() mesh.set_normals(normals) mesh.swap_normals("XZY", "x")
Mesh.set_normals_indices¶
- Mesh.set_normals_indices(normalsi, fm="Triangles", tp="Short")
-
Assigns the transferred normal vector indices to the mesh.
Parameters: normalsi : tuple or list or bytes
The index data of the normal vectors.
fm : str
Specifies the format in which the data is transmitted.
tp : str
Specifies the data type of the transmitted faces.
Example
# Transmission of the list with tuples normalsi = [(0, 1 , 2), (2, 0, 3)] mesh = mrp.get_mesh() mesh.set_normlas_indices(normalsi)
Mesh.swap_normals_indices¶
- Mesh.swap_normals_indices(fm="Triangles", tp="Short")
-
Converts normal vector indices of mesh if they have been passed.
Parameters: fm : str
The format of the conversion. The argument may take the following values: "Triangles", "TStrip", "TStripFF". TStrip – Triangle Strip TStripFF – Triangle Strip with division 0xFFFF.
tp : str
The data type. It may take the following values: "Integer", "Short", "Byte".
Mesh.set_color¶
- Mesh.set_color(r, g, b)
-
Specify the color of the faces of the mesh in the RGB format.
Parameters: r : int
Red in range [0, 255]
g : int
Green in range [0, 255]
b : int
Blue in range [0, 255]
Mesh.set_color_hsv¶
- Mesh.set_color_hsv(h, s, v)
-
Specify the color of the faces of the mesh in the HSV format.
Parameters: h : int
Hue in range [0, 360]
s : int
Saturation in range [0, 100]
v : int
Value in range [0, 100]
Mesh.set_material¶
- Mesh.set_material(mat)
-
Assigns the material to the mesh.
Parameters: mat : Object Material
Material is an object Material.
Mesh.set_material_faces¶
- Mesh.set_material_faces(mat_faces)
-
Assigns materials to the mesh. It lets you to specify a material for each polygon.
Parameters: mat_faces : dict
The wordindex, where the key is the face number (starting at 0) and the value is the material.
Example
import mrp mat1 = mrp.create_material("Mat1") mat1.set_color((255,0,0)) mat2 = mrp.create_material("Mat2") mat2.set_color((0,255,0)) mats = {0 : mat1, 1: mat2} mesh = mrp.get_mesh() mesh.set_material_faces(mats)
Объект Material
Material.set_color¶
- Material.set_color(r, g, b)
-
Specify the color of the faces of the mesh in the RGB format.
Parameters: r : int
Red in range [0, 255]
g : int
Green in range [0, 255]
b : int
Blue in range [0, 255]
Material.set_color_hsv¶
- Material.set_color_hsv(h, s, v)
-
Specify the color of the faces of the mesh in the HSV format.
Parameters: h : int
Hue in range [0, 360]
s : int
Saturation in range [0, 100]
v : int
Value in range [0, 100]
Material.set_texture¶
- Material.set_texture(image, mode="RGB", flip=True)
-
Sets the texture to the material.
Parameters: image : str
Full path to texture image
mode : str
Mode, color model of the image. It may take the following values: "RGB", "RGBA".
flip : bool
If True, turns on the image vertically.
Объект BufferFile
- BufferFile.set_byte_order()
- BufferFile.read()
- BufferFile.seek()
- BufferFile.tell()
- BufferFile.tellHex()
- BufferFile.reads()
- BufferFile.readByte()
- BufferFile.readbyte()
- BufferFile.readShort()
- BufferFile.readshort()
- BufferFile.readInt()
- BufferFile.readint()
- BufferFile.readFloat()
- BufferFile.readDouble()
- BufferFile.readHalfFloat()
- BufferFile.read3Short()
- BufferFile.read3short()
- BufferFile.read2Short()
- BufferFile.read2short()
- BufferFile.read3Int()
- BufferFile.read3int()
- BufferFile.read2Int()
- BufferFile.read2int()
- BufferFile.read3Float()
- BufferFile.read2Float()
BufferFile.set_byte_order¶
- BufferFile.set_byte_order(byte_order)
-
Sets the order in which bytes are read.
Parameters: byte_order : str
Specifies the byte order in which the data will be read. It can take two values: "<" – reverse order (Little Endian); ">" – direct order (Big Endian);
BufferFile.read¶
- BufferFile.read(size = -1)
-
Reads the specified number of bytes.
Parameters: size : int
Number is the maximum number of bytes to read. If you do not specify a parameter or the number has negative value, the contents of the file will be fully read.
Returns: Byte string
BufferFile.seek¶
- BufferFile.seek(offset, whence = 0)
-
Moves the current position of the pointer to the specified location in the file.
Parameters: offset : int
Offset in bytes.
from_what : int
Indicates where the offset should come from. It may take the following values:
0 — from the beginning of the file;
1 — from the current position;
2 — from the end of the file.
BufferFile.tell¶
- BufferFile.tell()
-
Returns the current position of the pointer in the file relative to its beginning.
Returns: The position of the pointer in the file.
BufferFile.tellHex¶
- BufferFile.tellHex()
-
Returns the current position of the pointer in the file relative to its beginning in hexadecimal form.
Returns: The position of the pointer in the file in hexadecimal form.
BufferFile.reads¶
- BufferFile.reads(fmt = "")
-
Reads and unpacks data from the structure. Analog of the struct.unpack()
Parameters: fmt : str
Data format.
> - direct order
< - reverse order
x - skip one byte
b - sign one byte
B - unsigned byte
h - signed short integer, 2 bytes
H - unsigned short integer, 2 bytes
i - signed integer, 4 bytes
I - unsigned integer, 4 bytes
l - long integer, 4 bytes
L - unsigned long integer, 4 bytes
Q - unsigned long integer, 8 bytes
f - floating point number, 4 bytes
d - double precision floating point number, 8 byte
p - counter and symbols, 1 + count byte
s - characters, count charactersReturns: Data tuple
Example
# Reads two unsigned numbers of 2 bytes and one floating-point number 4 bytes. f = mrp.get_bfile() a, b = f.reads("HH") с = f.reads("f")[0]
BufferFile.readByte¶
- BufferFile.readByte()
-
Reads a byte and returns a whole unsigned number.
Returns: Number
BufferFile.readbyte¶
- BufferFile.readbyte()
-
Reads the byte and returns the signed integer number.
Returns: Number
BufferFile.readShort¶
- BufferFile.readShort()
-
Reads 2 bytes and returns a whole unsigned number.
Returns: Number
BufferFile.readshort¶
- BufferFile.readshort()
-
Reads 2 bytes and returns the signed integer number.
Returns: Number
BufferFile.readInt¶
- BufferFile.readInt()
-
Reads 8 bytes and returns a whole unsigned number.
Returns: Number
BufferFile.readint¶
- BufferFile.readint()
-
Reads 4 bytes and returns the signed integer number.
Returns: Number
BufferFile.readFloat¶
- BufferFile.readFloat()
-
Reads 4 bytes and returns a floating-point number.
Returns: Number
BufferFile.readDouble¶
- BufferFile.readDouble()
-
Reads 8 bytes and returns a floating-point number.
Returns: Number
BufferFile.readHalfFloat¶
- BufferFile.readHalfFloat()
-
Reads 2 bytes and returns a floating-point number.
Returns: Number
BufferFile.read3Short¶
- BufferFile.read3Short()
-
Reads 6 bytes and returns a tuple of 3 integer unsigned numbers.
Returns: 3-digit tuple
Example
f = mrp.get_bfile() a,b,c = f.read3Short()
BufferFile.read3short¶
- BufferFile.read3short()
-
Reads 6 bytes and returns a tuple of 3 integer signed numbers.
Returns: 3-digit tuple
BufferFile.read2Short¶
- BufferFile.read2Short()
-
Reads 4 bytes and returns a tuple of 2 integer unsigned numbers.
Returns: 2-digit tuple
BufferFile.read2short¶
- BufferFile.read2short()
-
Reads 4 bytes and returns a tuple of 2 integer signed numbers.
Returns: 2-digit tuple
BufferFile.read3Int¶
- BufferFile.read3Int()
-
Reads 12 bytes and returns a tuple of 3 integer unsigned numbers.
Returns: 3-digit tuple
BufferFile.read3int¶
- BufferFile.read3int()
-
Reads 12 bytes and returns a tuple of 3 integer signed numbers.
Returns: 3-digit tuple
BufferFile.read2Int¶
- BufferFile.read2Int()
-
Reads 8 bytes and returns a tuple of 2 integer unsigned numbers.
Returns: 2-digit tuple
BufferFile.read2int¶
- BufferFile.read2int()
-
Reads 8 bytes and returns a tuple of 2 integer signed numbers.
Returns: 2-digit tuple
BufferFile.read3Float¶
- BufferFile.read3Float()
-
Reads 12 bytes and returns a tuple 3-number tuple with a floating point.
Returns: 3-digit tuple
BufferFile.read2Float¶
- BufferFile.read2Float()
-
Reads 8 bytes and returns a tuple 2-number tuple with a floating point.
Returns: 2-digit tuple