3D Model Researcher - Guide3D Model Researcher - Руководство
3D Model Researcher
Extract 3D models


Download 3D Model Researcher v2.8

Current Version: v2.8 28-08-2021

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.
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.
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.
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 characters

Returns:

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