# mm python module documentation

The mm python module is a wrapper for the SWIG-generated mmapi python module. The purpose of this module is to provide shorter, more convenient function names, that respect python conventions.

The mm module is organized into various top-level modules:

core meshmixer manipulation modules:

- `mm.scene`: Scene manipulation
- `mm.selection`: create/manipulate Selections
- `mm.tool`: run Tools, set parameters

meshmixer query modules:

- `mm.convert`: conversion utility functions
- `mm.util`: spatial queries

utility modules:

- `mm.frame`: mmFrame class
- `mm.mm_math`: linear algebra, math utilities

# Important Notes

This documentation was generated on December 10, 2014, the current version of meshmixer at this time is 2.7. You can get the most recent version of the mm-api package, including the mm module and this documentation, at https://github.com/meshmixer/mm-api

Please also see the github mainpage readme (ie follow the link above) for more details on the mm-api package, including setup instructions. This package is under active development and will change frequently. In particular, you must have a version compatible with the meshmixer installation you are running.

# Usage Tips

These modules all depend on the `mmapi` module, which is part of the mm-api package, found in the `/distrib/python` folder.

You can `import mm` and then access most top-level functions as `mm.<function_name>`, rather than importing each sub-module. However, specifically for the math manipulation functions, you may find you can write cleaner code by also adding `import mm.mm_math`.

The Meshmixer desktop application uses a normalized coordinate system internally. These coordinates are referred to as Scene coordinates, versus World coordinates, which are in the current physical dimensions of the scene. Currently many API functions expect and return points/dimensions in this space. See the `mm.convert` module for details on converting between Scene and World coordinates.

# Meshmixer Manipulation Modules

## mm.scene module

`mm.scene.``append_objects_from_file`(remote, filename)

  Read objects from a mesh file, append them to the scene, and return a list of new object IDs

`mm.scene.``clear_target`(remote)

  clear the current Target object setting

`mm.scene.``delete_objects`(remote, objects_list)

  Delete the scene objects corresponding to the IDs in objects_list

`mm.scene.``find_object_by_name`(remote, obj_name)

  Find the ID of the scene object with the given string name. Returns a 2-tuple (boolFound, object_id)

`mm.scene.``get_object_name`(remote, object_id)

  Return the string name of the scene object with the given ID

`mm.scene.``list_objects`(remote)

  Return a list of object IDs for the current scene

`mm.scene.``list_selected_groups`(remote)

  Returns a list of unique facegroup IDs for the current face selection (requires an active selection)

`mm.scene.``list_selected_objects`(remote)

  Returns a list of object IDs for the current set of selected scene objects

`mm.scene.``open_mix`(remote, path)

  Open a .mix file at the given location

`mm.scene.``save_mix`(remote, path)

  Save the current scene as a .mix file at the given location

`mm.scene.``select_objects`(remote, objects_list)

  Set the current objects selection to be the set of scene objects corresponding to the IDs in objects_list

`mm.scene.``set_as_target`(remote)

  Set the current scene object as the Target object

`mm.scene.``set_object_name`(remote, object_id, new_name)

  Modify the string name of the scene object with the given ID

## mm.selection module

`mm.selection.``clear_face_selection`(remote)

  Clear the current face selection (if there is one) and exit the Selection Tool

`mm.selection.``select_all`(remote)

  Select all faces of the active object (will initialize a Selection Tool if necessary)

`mm.selection.``select_facegroups`(remote, groups_list)

  Select the faces which have a facegroup ID in groups_list

`mm.selection.``select_inside_sphere`(remote, sphere_center, sphere_radius)

  Select the faces inside the sphere with given center/radius. Requires active Selection Tool.

`mm.selection.``selection_utility_command`(remote, command_name)

  Run a selection utility command (see ::AppendSelectUtilityCommand in StoredCommands.h)

## mm.tool module

- Tool string names: Tool Strings
- Tool parameters: Tool Parameters

`mm.tool.``accept_tool`(remote)

  Accept the current tool

`mm.tool.``begin_tool`(remote, tool_name)

  Begin execution of the Tool called tool_name

`mm.tool.``cancel_tool`(remote)

  Cancel the current tool

`mm.tool.``get_toolparam`(remote, param_name)

  Returns the current value of the given Tool parameter, or empty list if the parameter is not found.

`mm.tool.``set_toolparam`(remote, param_name, f)

  Set the parameter param_name of the current tool. This function handles int,float,boolean,vector3,and matrix9 inputs

`mm.tool.``tool_utility_command`(remote, command_name, arg=-99)

  Run a Tool utility command, with optional argument (see ::AppendToolUtilityCommand in StoredCommands.h)

`mm.tool.``toolquery_new_groups`(remote)

  Get a list of new groups created by last tool (NOTE: many Tools do not support this yet!)

# Meshmixer Query Modules

## mm.convert module

This module contains functions for converting to/from Meshmixer API values, including:

1. Conversion between SWIG-generated API helper structs/classes and python lists/tuples
2. Conversion between Meshmixer’s internal World and Scene coordinates

World/Scene coordinate conversion is one complication of Meshmixer that is not exposed in the desktop application, but must (currently) be managed by API clients.

Meshmixer internally re-scales imported meshes to a normalized coordinate space, ie a 2x2x2 unit box centered at the origin. API functions for spatial queries, bounding boxes, etc, currently expect points and dimensions in this normalized space, and return normalized results as well.

You can use the functions in this module to convert between Scene and World coordinates, where World coordinates are in the current units selected in the Units/Dimension Tool. By default, new scenes (i.e. after an import) have units in millimetres.

`mm.convert.``toS`(remote, v)

  same as to_scene(), but shorter

`mm.convert.``toW`(remote, v)

  same as to_world(), but shorter

`mm.convert.``to_scene`(remote, v)

  convert input from World space to Scene space (dimension or 3D point)

`mm.convert.``to_scene_f`(remote, f)

  convert a scalar dimension from World space to Scene space

`mm.convert.``to_scene_xyz`(remote, x, y, z)

  convert a 3D point from World space to Scene space

`mm.convert.``to_world`(remote, v)

  convert input from Scene space to World space (dimension or 3D point)

`mm.convert.``to_world_f`(remote, f)

  convert a scalar dimension from Scene space to World space

`mm.convert.``to_world_xyz`(remote, x, y, z)

  convert a 3D point from Scene space to World space

`mm.convert.``vectori_to_list`(vi)

  convert a SWIG vectori object to a Python list

`mm.convert.``vectorub_to_string`(vub)

  convert a SWIG vectorub object to a Python string

## mm.util module

This module contains spatial query functions, i.e. functions which return bounding-boxes, find nearest-point-on-surface, ray-cast, etc.

This module is likely to be renamed in the near future

`mm.util.``find_nearest`(remote, position)

  Find the nearest point on the 3D surface to the input 3-tuple. Returns a tuple (bOK, hitFrame), where bOK is a boolean indicating if a nereast point was found, and hitFrame is an mmFrame at the hit point, with Z axis oriented to the surface normal

`mm.util.``find_ray_hit`(remote, ray_origin, ray_direction)

  Find the intersection of a ray (specified by 3-tuples for origin and direction) and the 3D surface. Returns a tuple (bOK, hitFrame), where bOK is a boolean indicating if a hit was found, and hitFrame is an mmFrame at the hit point, with Z axis oriented to the surface normal

`mm.util.``get_face_selection_bounding_box`(remote)

  return the axis-aligned bounding box of the selected faces as two 3-tuples (min, max). Requires active face selection.

`mm.util.``get_face_selection_centroid`(remote)

  return the geometric centroid of the selected faces as a 3-tuple. Requires active face selection.

`mm.util.``get_selected_bounding_box`(remote)

  return the axis-aligned bounding box of the selected objects as two 3-tuples (min, max)

# Utility Modules

These modules do not actually make meshmixer API calls, they are included to make it easier to use the python API, and/or to write sample code.

## mm.frame module

class `mm.frame.``mmFrame`

  Bases: `object`

  This class represents a 3D frame with an origin (.origin) and .x/.y/.z ortho-normal axes.

  `get_matrix`()

    return orientation as 9-element tuple

  `set`(o, x, y, z)

    initialize with origin and X/Y/Z axes

  `setFromMM`(f)

    initialize with wrapped C++ frame3f object, see StoredCommands.h

## mm.mm_math module

`mm.mm_math.``addv3`(a, b)

  add 3-vector b to a

`mm.mm_math.``addv3s`(vec, scalar)

  add scalar to elements of 3-vector

`mm.mm_math.``addvs`(vec, s)

  add scalar to elements of vector

`mm.mm_math.``deg_to_rad`(angle)

  convert angle from degrees to radians

`mm.mm_math.``divv3s`(vec, scalar)

  divide elements of 3-vector by scalar

`mm.mm_math.``divvs`(vec, s)

  divide elements of vector by scalar

`mm.mm_math.``dotv3`(a, b)

  dot product of 3-vectors a and b

`mm.mm_math.``lerpv3`(a, b, t)

  linear interplation (1-t)*a + (t)*b

`mm.mm_math.``make_matrix_from_axes`(x, y, z)

  construct orientation matrix from basis vectors

`mm.mm_math.``make_rotX_matrix`(angle)

  construct matrix that rotates around X axis by angle (in radians)

`mm.mm_math.``make_rotY_matrix`(angle)

  construct matrix that rotates around Y axis by angle (in radians)

`mm.mm_math.``make_rotZ_matrix`(angle)

  construct matrix that rotates around Z axis by angle (in radians)

`mm.mm_math.``mulv3s`(vec, scalar)

  multiply elements of 3-vector by scalar

`mm.mm_math.``mulvs`(vec, s)

  multiply elements of vector by scalar

`mm.mm_math.``negv3`(a)

  negate 3-vector

`mm.mm_math.``rad_to_deg`(angle)

  convert angle from radians to degrees

`mm.mm_math.``subv3`(a, b)

  subtract 3-vector b from a

`mm.mm_math.``subv3s`(vec, scalar)

  subtract scalar from elements of 3-vector

`mm.mm_math.``subvs`(vec, s)

  subtract scalar from elements of vector

`mm.mm_math.``transpose`(matrix)

  return the transpose of a matrix stored as a 9-element tuple

## Module contents

# Indices and tables

- Index
- Module Index
- Search Page