
*******************
Metaball Properties
*******************

All metaball objects of a same :ref:`family <meta-ball-object-families>` in a scene interact with each other.
The settings in the *Metaball* section apply to all meta objects of the active family. In Edit Mode,
the *Active Element* panel is shown for :ref:`editing <meta-ball-editing>` individual metaball elements.


Metaball
========

.. reference::

   :Mode:      Object and Edit Mode
   :Panel:     :menuselection:`Properties --> Metaball --> Metaball`

.. figure:: /images/modeling_metas_properties_metaball-panel.png

   Family meta properties.

Resolution Viewport
   Controls the resolution of the resultant mesh as generated by the *Meta* objects.
   The 3D Viewport resolution of the generated mesh; finest to coarsest.
Render
   The rendered resolution of the generated mesh; finest to coarsest.

.. tip::

   One way to see the underlying mathematical structure is to lower the *Resolution*,
   increase the *Threshold* and set the *Stiffness* (see below)
   a fraction above the *Threshold*. Fig. :ref:`fig-meta-intro-underlying` is a meta cube
   with the above mentioned configuration applied as follows:
   *Resolution* of 0.410, *Threshold* of 5.0 and *Stiffness* a fraction above at 5.01.

   .. list-table::

      * - .. _fig-meta-intro-underlying:

          .. figure:: /images/modeling_metas_properties_underlying-structure.png

             Underlying structure.

        - .. figure:: /images/modeling_metas_properties_underlying-structure-shape.png

             Meta cube shape.

   You can clearly see the underlying cubic structure that gives the meta cube its shape.

Influence Threshold
   Defines how much a meta's surface "influences" other metas.
   It controls the *field level* at which the surface is computed.
   The setting is global to a group of *Meta* objects.
   As the threshold increases, so does the influence that each meta has on each other.

   There are two types of :ref:`influence <meta-ball-editing-negative-influence>`: *positive* or *negative*.

Update on Edit
   While transforming metas (move, scale, etc.), you have four "modes" of visualization.

   This should help you if you experience difficulties (metas are quite computationally intensive...),
   but with modern computers, this should not happen, unless you use many metas,
   or very high resolutions...

   :Always:
      Fully display the meta during transformations.
   :Half:
      During transformations, display the meta at half its *Viewport* resolution.
   :Fast:
      Do not display meta during transformations.
   :Never:
      Never show meta mesh (not a very recommended option, as the meta is only visible at render time!).


Active Element
==============

.. reference::

   :Mode:      Edit Mode
   :Panel:     :menuselection:`Properties --> Metaball --> Active Element`

.. figure:: /images/modeling_metas_properties_active-element-panel.png
   :align: right

   Active Element panel.

These settings apply only to the selected metaball element.

Type
   Changes the :doc:`primitive shape </modeling/metas/primitives>` of the meta object.

Stiffness
   Controls the influence range for individual metaball elements, unlike *Influence Threshold*
   which controls the influence for the entire :ref:`meta family <meta-ball-object-families>`.
   This essentially defines how sensitive a meta is to being affected by other metas.
   With a low stiffness, the meta will begin to deform from further away.
   A higher value means the meta needs to be close to another one to begin merging.
   The *Stiffness* is visualized by the *green ring* and can be selected and :ref:`scaled <bpy.ops.transform.resize>`
   to also change the *Stiffness* value.

   To be visible, the *Stiffness* must be slightly larger than the *Threshold* value.

   .. _fig-meta-edit-stiffness:

   .. figure:: /images/modeling_metas_editing_stiffness.png
      :align: center
      :width: 450px

      The left meta ball, has a smaller *Stiffness* value than the right one.

Radius
   Controls the physical size of the metaball.
   This works the same as scaling the metaball in Object Mode.
   The *Radius* is visualized by the *white ring* and can be selected and :ref:`scaled <bpy.ops.transform.resize>`
   to also change the *Radius* value.

.. _meta-ball-editing-negative-influence:

Negative
   Controls whether the influence is *positive* or *negative*.

   A *positive* influence is defined as an attraction,
   meaning that the meshes will stretch towards each other as the *rings of influence* intersect.
   The opposite effect would be a *negative* influence where the objects repel each other.

   .. note::

      If a metaball has *Negative* influence the meta is not visible in the 3D Viewport,
      only the surrounding circles are shown.

   .. list-table::

      * - .. figure:: /images/modeling_metas_editing_family.png

             Positive influence of three metaballs.

        - .. figure:: /images/modeling_metas_editing_negative-influence.png

             Negative influence of a meta ball;
             the first is negative and the second positive.

.. _bpy.ops.mball.hide_metaelems:
.. _bpy.ops.mball.reveal_metaelems:

Hide
   As in :ref:`object-show-hide` in Object Mode, you can hide the selected meta(s),
   and then reveal what was hidden. This is very handy for cleaning your views up a bit.

   .. note::

      - Hiding a meta does not *only* hide it, but also disables it from the meta computation,
        which will affect the final geometry.

      - The two red and green rings always remain visible in Edit Mode,
        as well as the select circle in Object Mode.
