[Bf-docboard-svn] bf-manual: [8840] trunk/blender_docs/manual/addons/import_export/mesh_atomic.rst: io_mesh_atomic: revision of the documentation
Clemens Barth
noreply at blender.org
Sat Jan 22 15:34:56 CET 2022
Revision: 8840
https://developer.blender.org/rBM8840
Author: blendphys
Date: 2022-01-22 15:34:55 +0100 (Sat, 22 Jan 2022)
Log Message:
-----------
io_mesh_atomic: revision of the documentation
After all the changes done at the add-on in the last week,
the documentation has been entirely reviewed and revised.
The revision includes:
- Added: add-on uses Principled BSDF shader
- Added: BSDF material properties in custom data file
- Added: explanation of the instancing vertice structure
(this was urgently needed, many people asked me how it works)
- Better explanations in general
- Updating Internet links
- Corrections
Modified Paths:
--------------
trunk/blender_docs/manual/addons/import_export/mesh_atomic.rst
Modified: trunk/blender_docs/manual/addons/import_export/mesh_atomic.rst
===================================================================
--- trunk/blender_docs/manual/addons/import_export/mesh_atomic.rst 2022-01-21 19:41:50 UTC (rev 8839)
+++ trunk/blender_docs/manual/addons/import_export/mesh_atomic.rst 2022-01-22 14:34:55 UTC (rev 8840)
@@ -7,30 +7,36 @@
(molecules, crystals, clusters, particles, surfaces, etc.), which are described in
PDB (``.pdb``) and XYZ files (``.xyz``) (`Import PDB/XYZ`_). The add-on reads the coordinates of
all atoms in the PDB/XYZ file and represents the atoms as balls in the Blender world.
-Also the sticks, which are described in PDB files only, can be shown if the sticks are listed in the PDB file.
+Also the sticks, which are described in PDB files only, are shown if the sticks are *explicitly* listed in the PDB file.
+The `Principled BSDF shader <https://docs.blender.org/manual/en/dev/render/shader_nodes/shader/principled.html>`__
+is used to describe the material properties of the atoms.
+
For the import, many options can be chosen, which allow representing the atoms and sticks in different ways.
With help of several tools in the `Atomic Blender Utilities panel`_, the atomic structures can be modified
-after the import. Note that the coordinates of selected atomic structures in the Blender 3D world
-can also be exported into PDB/XYZ files.
+after the import.
-Atomic Blender (PDB/XYZ) is interesting for scientists, who want to
-visualize their atomic structures described in PDB or XYZ files with Blender.
+Note that the coordinates of selected atomic structures in the Blender 3D world
+can also be *exported* into PDB/XYZ files.
+
+
+**General motivation:** Atomic Blender (PDB/XYZ) is interesting for scientists, who want to
+visualize with Blender their atomic structures described in PDB or XYZ files.
Thanks to Blender, fancy graphics of molecules, crystal structures, surfaces,
nanoparticles, clusters and complex atomic arrangements can be obtained.
Such graphics meet the standards of top-level journals, which have a high impact factor.
See `Examples`_ at the end of this page.
-.. seealso:: Info about PDB and XYZ
+.. seealso:: **Info about PDB and XYZ**
- Description of the PDB file format:
`Wikipedia <https://en.wikipedia.org/wiki/Protein_Data_Bank_(file_format)>`__ and
- `RCSB <https://www.rcsb.org/pdb/static.do?p=file_formats/pdb/index.html>`__.
+ `RCSB <http://www.wwpdb.org/documentation/file-format>`__.
- Description of the XYZ file format:
`Wikipedia <https://en.wikipedia.org/wiki/XYZ_file_format>`__ and
`Open Babel <https://openbabel.org/docs/dev/FileFormats/XYZ_cartesian_coordinates_format.html>`__.
- - Some notes about PDB and XYZ files can also be found on one of
- the `developer's site <https://development.root-1.de/Atomic_Blender_PDB_XYZ.php>`__ and
- `remarks <https://development.root-1.de/Atomic_Blender_PDB_XYZ_Remarks.php>`__.
+ - Some notes about PDB and XYZ files can also be found
+ `here <https://development.root-1.de/Atomic_Blender_PDB_XYZ.php>`__ and
+ `here <https://development.root-1.de/Atomic_Blender_PDB_XYZ_Remarks.php>`__.
- Many molecules can be downloaded from the `RCSB site <https://www.rcsb.org/>`__ (go to 'Download').
- A list of software that deals with PDB in different ways can be found on
the `RCSB site <https://www.rcsb.org/pages/thirdparty/molecular_graphics>`__. There also is
@@ -38,18 +44,20 @@
`quantum chemical calculators <https://en.wikipedia.org/wiki/List_of_quantum_chemistry_and_solid-state_physics_software>`__
used in research, which can create or even calculate atomic structures and store them in PDB/XYZ files.
-.. seealso:: Forum
+.. seealso:: **Forum**
- - Please, use the `Blender Artists forum <https://blenderartists.org/t/1197801>`__ for comments and questions.
+ - Please, use the `Blender Artists forum <https://blenderartists.org/t/1197801>`__ for comments and questions or
+ directly the `Blender chat <https://blender.chat/home>`__.
- There also is the possibility to ask questions on
`Stack Exchange <https://blender.stackexchange.com/>`__. However,
- note that some of the developers (like Blendphys) don't have enough credits,
- which are needed to give answers on Stack Exchange.
+ note that some of the developers like Blendphys don't have enough credits, which are,
+ however, needed to have the permission for giving answers on Stack Exchange.
-.. hint:: Defects in an Atomic Structure
+.. hint:: **Defects in an Atomic Structure**
If you want to show defects like vacancies in an atomic structure, use an 'X' for
- the element name in the PDB or XYZ file. A defect is shown in the form of a cube.
+ the element name in the PDB or XYZ file (`see here <https://development.root-1.de/Atomic_Blender_PDB_XYZ_Remarks.php>`__).
+ A defect is shown in the form of a cube.
Import PDB/XYZ
@@ -88,7 +96,7 @@
Type Of
Choose either *NURBS*, *Mesh* or *Metaballs* for the atoms.
- For option *Mesh* the *Azimuth* and *Zenith* values can be chosen.
+ For option *Mesh*, the *Azimuth* and *Zenith* values can be chosen.
Metaballs can lead to some fancy effects: for instance,
if enough large, their shapes melt together showing some kind of surface effect.
@@ -102,7 +110,7 @@
The atom radii as well as the distances between the atoms can be scaled by a simple factor.
Type
- The type of atom radius (atomic, van der Waals or as specified in the custom data file [predefined]) can be chosen.
+ The type of atom radius (atomic, van der Waals or as predefined) can be chosen.
Sticks/Bonds (only PDB)
@@ -109,7 +117,9 @@
-----------------------
Use Sticks
- Use sticks or not.
+ Use sticks or not. Note that the sticks must be listed in the PDB file.
+ The add-on does not 'calculate' possible bonds between atoms, which are then
+ shown as sticks!
Type
In general, the options *Sector* and *Radius* determine the precision and dimension of the sticks, respectively.
@@ -118,16 +128,16 @@
showing the colors of the respective two atoms which it connects.
Instancing Vertices
- The sticks of one element are put into one instancing vertices structure and the sticks appear as cylinders.
- The instancing vertices structure makes the displaying and loading of many sticks relatively fast
- (`Separate Atoms`_ for more info). Options *Unit* is the length of a unit (a small cylinder):
+ The sticks of one element are put into one instancing vertice structure and the sticks appear as cylinders.
+ The instancing vertice structure makes the displaying and loading of many sticks relatively fast
+ (see Section `The instancing vertice structure`_ for more info). Options *Unit* is the length of a unit (a small cylinder):
several of such units are put together forming actually the stick (cylinder).
The longer the unit length is the less is the number of such units and
thus the faster is the displaying. However, if the unit length is too long the stick becomes
- eventually longer than the bond length, which the stick will actually represent.
- This then creates some overlapping effects. Option *Bonds*
+ eventually longer than the bond length (distance between atoms).
+ This can then lead to a 'overlapping effect' where a stick intersects the atoms. Option *Bonds*
displays apart from single also double, triple, etc. bonds whereas
- option *Distance* is the corresponding bond distance measured in stick diameter.
+ option *Distance* is the distance between the bonds measured in stick diameter.
Skin
The skin and subdivision modifiers are used to build the sticks.
This gives a nice network of sticks, which can be used to show,
@@ -156,9 +166,85 @@
.. important::
- The number of atoms in a frame has to be the **same** for all frames!
+ **Please, keep in mind**: the number of atoms in a frame has to be the **same** for all frames!
+The instancing vertice structure
+================================
+.. figure:: /images/addons_import-export_mesh-atomic_dupli_1.png
+ :align: right
+ :width: 300px
+
+ The NaCl structure in the outliner.
+
+It is essential to understand, how the atoms (and sticks) of an atomic structure are
+organized inside Blender. This is why we focus a little bit onto this in the following:
+
+When atomic structures are imported via the PDB or XYZ importer, the atoms are put
+into a so-called *instancing vertice structures*, somewhat into 'groups' of elements.
+For instance, all sodium atoms of a NaCl structure form one instancing vertice structure,
+and the same applies for the chlorine atoms (see figure). In the case of the sodium
+atoms, there is a collection *Sodium* that includes the collection *Sodium_atom*.
+Within the latter, the *Sodium_mesh* is composed of the mesh itself (*Mesh_Sodium*)
+and a ball called *Sodium_ball*. The mesh only contains vertices (no objects!),
+and the vertices are located at the x,y,z positions specified in the PDB/XYZ file.
+What Blender is doing is simply 'duplicating' the 'representative'
+ball *Sodium_ball* at all the vertices! Because only **one ball** is used, it
+makes things incredibly fast by representing, e.g., a thousand of atoms inside Blender.
+Note that the representative ball is in the center of the structure,
+without having any meaning. This is the reason why the visibility switch
+of the representative ball is switched off (see red arrow)!
+
+There are some consequences:
+a) The representative ball appears at all vertices with the same orientation.
+b) Changing the material properties of the representative ball changes the properties of
+all duplicated balls.
+c) A ball is NOT an individual object, it is rather a linked member of the
+structure. Actually, the object as such does not exist.
+
+.. figure:: /images/addons_import-export_mesh-atomic_dupli_2.png
+ :align: right
+ :width: 300px
+
+ The NaCl structure in the outliner.
+
+Modifications
+-------------
+
+Displacing an 'individual' atom
+ For this, the respective vertice has to be displaced: go into the *Edit Mode*
+ and select the atom. You can now displace the atom (vertice).
+
+Changing material properties (of all atoms)
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-docboard-svn
mailing list