.. _blender material:

Creating and Setting Materials
==============================

pyddg provides utilities to work with simple Blender materials.

.. warning::
 All our utilities only create and work with materials consisting of a single
 `Principled BSDF <https://docs.blender.org/manual/en/latest/render/shader_nodes/shader/principled.html>`_ node.

.. contents:: Table of contents
   :local:
   :backlinks: none

Quick start
-----------

To create and set materials of Blender objects one can use:

.. literalinclude:: ../../../../../examples/blender/docs/material.py
   :language: python
   :start-after: [creating and setting]
   :end-before: [creating and setting]

.. image:: material/default.png
				
One can also set any existing material by refering to its name.
If the material does not exist, a new one is created with default parameters.

.. literalinclude:: ../../../../../examples/blender/docs/material.py
   :language: python
   :start-after: [set by name]
   :end-before: [set by name]


More options at creation
------------------------

One can set basic properties of the materials this way:

.. literalinclude:: ../../../../../examples/blender/docs/material.py
   :language: python
   :start-after: [setting material properties]
   :end-before: [setting material properties]

.. image:: material/blue.png

Color
^^^^^
		   
The color argument sets the color as a (red, green, blue) tuple with values between 0 and 1. So (1, 0, 0) is red and (0, 1, 1) is cyan.

Shininess
^^^^^^^^^

The specular value is a mesure of the shininess, while the roughness quantifies how sharp this shininess appears. It is best to play with these parameters to get a feeling for their effects.

Transparency
^^^^^^^^^^^^

The alpha argument sets the opacity of the material.

.. literalinclude:: ../../../../../examples/blender/docs/material.py
   :language: python
   :start-after: [make transparent]
   :end-before: [make transparent]

.. image:: material/transparent.png


Modifying materials
-------------------

Arbitrary input parameters of the BSDF node of a material can be changed this way:

.. literalinclude:: ../../../../../examples/blender/docs/material.py
   :language: python
   :start-after: [set value]
   :end-before: [set value]

.. image:: material/modified.png