Code cleanup, bug fixes and documentation (#122)

- Cleaning up the source code. Removed all the last remaining references to Tundra.
- Fixed bug with mesh previewer button
- Fixed bug with incorrect setting for "USER_MATERIALS". If it was set to a directory like "C:\" it scans recursively then crashes when it hits a directory it doesn't have access too.
- Updated readme with installation procedure and mesh previewer

README.md

@@ -10,6 +10,7 @@
  - [Exporting Meshes](#exporting-meshes)
 	- [Ogre Mesh](#ogre-mesh-v1)
 	- [OgreNext Mesh](#ogrenext-mesh-v2)
+ 	- [Output Filenames](#output-filenames)
  - [Importing Meshes](#importing-meshes)
  - [Additional Features](#additional-features)
 	- [Merge Objects on export](#merge-objects-on-export)
@@ -20,20 +21,23 @@
 	- [Exporting Particle Systems](#exporting-particle-systems)
 	- [Exporting Shape (or Pose) Animations](#exporting-shape-animations)
 	- [Exporting Node Animations](#exporting-node-animations)
+ 	- [Mesh Previewer](#mesh-previewer)
  - [About](#about)
  - [Authors](#authors)
 
 ## Installing
 1. Copy the [io_ogre](io_ogre) folder into the [$BLENDER_DIR](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)`/scripts/addons` folder.
-  - Windows = %USERPROFILE%\AppData\Roaming\Blender Foundation\Blender\[VERSION]\scripts\addons
-
-2. Set the correct path to `OGRETOOLS_XML_CONVERTER` in [io_ogre/config.py](io_ogre/config.py) (Line 108) prior to the first run.
-  - If you want to export meshes for Ogre (v1): Then this path should point to `OgreXMLConverter.exe`. This file can be found in the [Ogre SDK](https://www.ogre3d.org/download/sdk/sdk-ogre)
-  - If you want to export meshes for OgreNext (v2.*): Then this path should point to `OgreMeshTool.exe`. This file can be found in the [OgreNext SDK](https://www.ogre3d.org/download/sdk/sdk-ogre-next)
-
+	- Windows = %USERPROFILE%\AppData\Roaming\Blender Foundation\Blender\[VERSION]\scripts\addons
+
+2. Configure the plugin by editing [io_ogre/config.py](io_ogre/config.py) prior to the first run.
+	- Set the correct path to `OGRETOOLS_XML_CONVERTER` (Line 105) 
+		- If you want to export meshes for Ogre (v1): Then this path should point to `OgreXMLConverter.exe`. This can be found in the [Ogre SDK](https://www.ogre3d.org/download/sdk/sdk-ogre)
+		- If you want to export meshes for OgreNext (v2.\*): Then this path should point to `OgreMeshTool.exe`. This can be found in the [OgreNext SDK](https://www.ogre3d.org/download/sdk/sdk-ogre-next)
+	- **[OPTIONAL]** Set `MESH_PREVIEWER` (Line 108) to a path pointed to `ogre-meshviewer.bat`. This can be found in [OGRECave/ogre-meshviewer](https://github.com/OGRECave/ogre-meshviewer/releases)      
+  	- Make sure that `USER_MATERIALS` isn't set to a directory like "C:\\\". The addon scans this path recursively and will crash when it hits a path it doesn't have permissions for.
+
 3. Enable the addon in Blender
-  - Version 2.9: `Edit menu > Preferences > Add-ons`. Search for `ogre` and click the box up the top left.
-  - Version 2.8: `User Preferences > Add-Ons > Import-Export` (CTRL+ALT+U). Search for `ogre` and check the box on the right. Remember to save as default if you want the addon to be enabled after you exit your Blender. Integrated help docs will be shown in the upper right hand toolbar, replacing blender's normal `Help` menu, read them for assistance.
+	- Version 2.9: `Edit menu > Preferences > Add-ons`. Search for `'ogre'` and click the box up the top left.
 
 The following versions of blender have been tested:
 * Blender 2.9x (partially tested. Exporting meshes & materials works)
@@ -50,7 +54,7 @@ If you are upgrading from a previous version of blender2ogre, and having problem
 * [Meshmoon: Video and text instructions how to install and use blender2ogre addon](http://doc.meshmoon.com/index.html?page=from-blender-to-meshmoon-part-1)
 
 ## Exporting Meshes
-To export a blender model: `File Menu > Export > Ogre3D (.scene & .mesh)`. If the menu button is greyed out, the select the object to export from the blender Node tree (Scene collections). 
+To export a blender model: `File Menu > Export > Ogre3D (.scene & .mesh)`. If the menu button is greyed out, the select the object to export from the blender Node tree (Scene collections) first. 
 
 #### Ogre Mesh (V1)
 If you have `OGRETOOLS_XML_CONVERTER` set to a "OgreXMLConverter.exe" path, then the export dialogue will display options relevant for the Ogre (v1) mesh format.
@@ -70,12 +74,21 @@ If you have `OGRETOOLS_XML_CONVERTER` set to a "OgreMeshTool.exe" path, then the
     - Tangents: "generate with parity"
     - Else Tangents: "none"
   - Optimise Vertex buffers for shaders: ticked
-  - Vertex buffer options: puqs
+  - Vertex buffer options: **puqs**
 
 You can check the arguments passed to `OgreMeshTool.exe` in the Blender console. (`Window Menu > Toggle System Console`)
 
 Blender will export the material format in a Ogre (V1) format. This is not compatible with OgreNext (V2.*). You should manually convert them to a material.json file. See the [Ogre Wiki: HLMS Materials](https://wiki.ogre3d.org/HLMS+Materials) for more information.
 
+#### Output Filenames
+The output file names are determined as per the following:
+![Output filenames example](images/Readme-ExportFilename-Example1.png)
+* If the collection name (Yellow box 1) *doesn't* have the prefix "merge." then the mesh filename is taken from the Scene Collection Node at location `[Red box 3]`. In this example: **CubeBig.mesh**
+* If the collection name (Yellow box 1) *does* have the prefix "merge." then the mesh filename is taken from the Scene Collection Node at location `[Yellow box 1, minus the 'merge.' prefix ]`. In this example: **CubeMerge.mesh**
+	- For more information on merging see the heading: [Merge Objects on export](#merge-objects-on-export)
+* The material filename is taken from the export dialogue filename text box at location `[Red box 2]`. The ".material" file extension is automatically added. In this example the output material name would be: **CubeSmall.material**
+* The material definition names are taken from the material names in the Scene Collection Node `[Red box 4]`. In this example: **CubeMaterial**
+
 ## Importing Meshes
 As of `blender2ogre` version *0.8.2*, the Kenshi Importer has been integrated into `blender2ogre` with the following features:
  - Import mesh from `.xml` as well as `.mesh` files
@@ -221,6 +234,13 @@ Then you can use `blender2ogre` to export the poses and animations into a `.mesh
 Node Animations are a way to have scripted node animations in your Ogre application.
 Check out the [Node Animations](NodeAnimations.md) tutorial to see how to create some animations for a couple of different scenarios.
 
+### Mesh Previewer
+If `OGRETOOLS_XML_CONVERTER` in [io_ogre/config.py](io_ogre/config.py) is set to a valid path, a button will appear allowing you to preview your mesh in Ogre3D. If the button isn't there, the path is invalid. This button only works for Ogre (V1) meshes.
+The button is located here:
+
+![Preview mesh button location](images/Readme-MeshPreviewButtonLocation.png)
+
+
 ## About
 [The original version of this](https://code.google.com/archive/p/blender2ogre/) was a *single* monolithic Python file.
 This is not maintainable, and contains a tremendous amount of bugs. There was the need to export blender model to ogre from

io_ogre/__init__.py

@@ -15,7 +15,7 @@
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 
 bl_info = {
-    "name": "OGRE Importer-Exporter (.scene, .mesh, .skeleton) and RealXtend (.txml)",
+    "name": "OGRE Importer-Exporter (.scene, .mesh, .skeleton)",
     "author": "Brett, S.Rombauts, F00bar, Waruck, Mind Calamity, Mr.Magne, Jonne Nauha, vax456, Richard Plangger, Pavel Rojtberg, Guillermo Ojea Quintana",
     "version": (0, 8, 2),
     "blender": (2, 80, 0),
@@ -80,12 +80,6 @@ def apply_preferences_to_config(self, context):
         default=config.CONFIG['OGRETOOLS_MESH_MAGICK'],
         update=apply_preferences_to_config
     )
-    TUNDRA_ROOT : bpy.props.StringProperty(
-        name="TUNDRA_ROOT",
-        subtype='FILE_PATH',
-        default=config.CONFIG['TUNDRA_ROOT'],
-        update=apply_preferences_to_config
-    )
     MESH_PREVIEWER : bpy.props.StringProperty(
         name="MESH_PREVIEWER",
         subtype='FILE_PATH',
@@ -110,7 +104,6 @@ def draw(self, context):
         layout.prop(self, "OGRETOOLS_XML_CONVERTER")
         layout.prop(self, "OGRETOOLS_MESH_UPGRADER")
         layout.prop(self, "OGRETOOLS_MESH_MAGICK")
-        layout.prop(self, "TUNDRA_ROOT")
         layout.prop(self, "MESH_PREVIEWER")
         layout.prop(self, "IMAGE_MAGICK_CONVERT")
         layout.prop(self, "USER_MATERIALS")
@@ -121,6 +114,7 @@ def register():
     logging.basicConfig(stream=sys.stdout, level=logging.DEBUG, format='[%(levelname)5s] %(message)s', datefmt='%H:%M:%S')
 
     logging.info('Starting io_ogre %s', bl_info["version"])
+
     # The UI modules define auto_register functions that
     # return classes that should be loaded by the plugin
     for clazz in ui.auto_register(True):

io_ogre/config.py

@@ -86,9 +86,6 @@
     #'DEBUG_LOGGING' : False,
     'SHOW_LOG_NAME' : False,
 
-    # Tundra
-    'TUNDRA_STREAMING' : True,
-
     # Import
     'IMPORT_NORMALS' : True,
     'MERGE_SUBMESHES' : True,
@@ -98,21 +95,20 @@
     'IMPORT_SHAPEKEYS' : True
 }
 
-_CONFIG_TAGS_ = 'OGRETOOLS_XML_CONVERTER OGRETOOLS_MESH_UPGRADER OGRETOOLS_MESH_MAGICK TUNDRA_ROOT MESH_PREVIEWER IMAGE_MAGICK_CONVERT USER_MATERIALS SHADER_PROGRAMS TUNDRA_STREAMING'.split()
+_CONFIG_TAGS_ = 'OGRETOOLS_XML_CONVERTER OGRETOOLS_MESH_UPGRADER OGRETOOLS_MESH_MAGICK MESH_PREVIEWER IMAGE_MAGICK_CONVERT USER_MATERIALS SHADER_PROGRAMS'.split()
 
 ''' todo: Change pretty much all of these windows ones. Make a smarter way of detecting
-    Ogre tools and Tundra from various default folders. Also consider making a installer that
+    Ogre tools from various default folders. Also consider making a installer that
     ships Ogre cmd line tools to ease the setup steps for end users. '''
 
 _CONFIG_DEFAULTS_WINDOWS = {
     'OGRETOOLS_XML_CONVERTER' : 'C:\\OgreCommandLineTools\\OgreXMLConverter.exe',
     'OGRETOOLS_MESH_UPGRADER' : 'C:\\OgreCommandLineTools\\OgreMeshUpgrader.exe',
     'OGRETOOLS_MESH_MAGICK' : 'C:\\OgreCommandLineTools\\MeshMagick.exe',
-    'TUNDRA_ROOT' : 'C:\\Tundra2',
-    'MESH_PREVIEWER' : 'C:\\OgreMeshy\\Ogre Meshy.exe',
+    'MESH_PREVIEWER' : 'C:\\OgreTools\\ogre-meshviewer\\ogre-meshviewer.bat',
     'IMAGE_MAGICK_CONVERT' : 'C:\\Program Files\\ImageMagick\\convert.exe',
-    'USER_MATERIALS' : 'C:\\Tundra2\\media\\materials',
-    'SHADER_PROGRAMS' : 'C:\\Tundra2\\media\\materials\\programs'
+    'USER_MATERIALS' : '',
+    'SHADER_PROGRAMS' : 'C:\\'
 }
 
 _CONFIG_DEFAULTS_UNIX = {
@@ -122,10 +118,9 @@
     'OGRETOOLS_XML_CONVERTER' : 'OgreXMLConverter',
     'OGRETOOLS_MESH_UPGRADER' : 'OgreMeshUpgrader',
     'OGRETOOLS_MESH_MAGICK' : '/usr/local/bin/MeshMagick',
-    'TUNDRA_ROOT' : '~/Tundra2',
     'MESH_PREVIEWER' : 'ogre-meshviewer',
-    'USER_MATERIALS' : '~/Tundra2/media/materials',
-    'SHADER_PROGRAMS' : '~/Tundra2/media/materials/programs',
+    'USER_MATERIALS' : '~/',
+    'SHADER_PROGRAMS' : '~/',
     #'USER_MATERIALS' : '~/ogre_src_v1-7-3/Samples/Media/materials',
     #'SHADER_PROGRAMS' : '~/ogre_src_v1-7-3/Samples/Media/materials/programs',
 }

io_ogre/meshy.py

@@ -6,8 +6,8 @@
 from .ogre.material import dot_materials
 from .util import objects_merge_materials, merge_objects
 
-## mesh previewer
-
+## This class is called when the "Preview Mesh" button is pressed. It opens the Ogre mesh previewer
+## The button is created int ui/__init__.py > auto_register() function.
 class OGREMESH_OT_preview(bpy.types.Operator):
     '''helper to open ogremesh'''
     bl_idname = 'ogremesh.preview'

io_ogre/ogre/material.py

@@ -391,6 +391,13 @@ def load_user_materials():
     # I think this is soley used for realxtend... the config of USER_MATERIAL
     # points to a subdirectory of tundra by default. In this case all parsing
     # can be moved to the tundra subfolder
+
+    # Exit this function if the path is empty. Allows 'USER_MATERIALS' to be blank and not affect anything.
+    # If 'USER_MATERIALS' is something too broad like "C:\\" it recursively scans and will crash when it
+    # hits directories it doesn't have access too
+    if config.get('USER_MATERIALS') == '':
+        return
+
     if os.path.isdir( config.get('USER_MATERIALS') ):
         scripts,progs = update_parent_material_path( config.get('USER_MATERIALS') )
         for prog in progs:

io_ogre/ogre/skeleton.py

@@ -67,9 +67,9 @@ def __init__(self, rbone, pbone, skeleton):
             self.fixUpAxis = False
         else:
             self.fixUpAxis = True
-            if config.get('SWAP_AXIS') == '-xzy':      # Tundra 1.x
+            if config.get('SWAP_AXIS') == '-xzy':      # 1.x
                 self.flipMat = mathutils.Matrix(((-1,0,0,0),(0,0,1,0),(0,1,0,0),(0,0,0,1)))
-            elif config.get('SWAP_AXIS') == 'xz-y':    # Tundra 2.x current generation
+            elif config.get('SWAP_AXIS') == 'xz-y':    # 2.x current generation
                 #self.flipMat = mathutils.Matrix(((1,0,0,0),(0,0,1,0),(0,1,0,0),(0,0,0,1)))
                 self.flipMat = mathutils.Matrix(((1,0,0,0),(0,0,1,0),(0,-1,0,0),(0,0,0,1))) # thanks to Waruck
             else:

io_ogre/todo.py

@@ -1,7 +1,4 @@
 
-# TODO TUNDRA def export_menu_func_realxtend(self, context):
-#    op = self.layout.operator(INFO_OT_createRealxtendExport.bl_idname, text="realXtend Tundra (.txml and .mesh)")
-
 ## Blender world panel options for EC_SkyX creation
 ## todo: EC_SkyX has changes a bit lately, see that
 ## all these options are still correct and valid
@@ -39,10 +36,8 @@ class PANEL_Object(bpy.types.Panel):
 
     @classmethod
     def poll(cls, context):
-        _USE_TUNDRA_ = False # TODO
-        if _USE_TUNDRA_ and context.active_object:
-            return True
-
+        return True
+
     def draw(self, context):
         ob = context.active_object
         layout = self.layout
@@ -93,10 +88,6 @@ def draw(self, context):
         if ob.use_multires_lod:
             box.prop( ob, 'multires_lod_range' )
 
-''' todo: Update the nonsense C:\Tundra2 paths from defaul config and fix this doc.
-    Additionally point to some doc how to build opengl only version on windows if that really is needed and
-    remove the old Tundra 7z link. '''
-
 @UI
 class PANEL_node_editor_ui_extra( bpy.types.Panel ):
     bl_space_type = 'NODE_EDITOR'

io_ogre/ui/__init__.py

@@ -21,13 +21,15 @@
 
 # This is only relevant on first run, on later reloads those modules
 # are already in locals() and those statements do not do anything.
+import os
 from .. import config
 from ..report import Report
 from . import material
 from . import importer
 from . import export
 from . import helper
 from ..meshy import OGREMESH_OT_preview
+from os.path import exists
 
 def add_preview_button(self, context):
     layout = self.layout
@@ -41,14 +43,21 @@ def auto_register(register):
     yield OGRE_MT_mini_report
     yield OGREMESH_OT_preview
 
-    bpy.types.VIEW3D_PT_tools_active.append(add_preview_button)
+    # 2021/09/19 - oldmanauz: I don't think this is the proper way to do this
+    # bpy.types.VIEW3D_PT_tools_active doesn't exist in the documentation here: https://docs.blender.org/api/current/bpy.types.html
+    # does this mean it is poorly supported, undefined or depreciated?
+    # Possible solution for future implemtation: bpy.utils.register_tool() & bpy.types.WorkSpaceTool;
+    if register and os.path.exists(config.get('MESH_PREVIEWER')):        
+        bpy.types.VIEW3D_PT_tools_active.append(add_preview_button) # Add the button if the addon is being enabled and the MESH_PREVIEWER path is valid
+    elif not register and os.path.exists(config.get('MESH_PREVIEWER')):
+        bpy.types.VIEW3D_PT_tools_active.remove(add_preview_button) # Remove the button if the addon is being disbaled and the MESH_PREVIEWER path is valid (Assumes that the button is only added if MESH_PREVIEWER was valid)
 
     yield from importer.auto_register(register)
     yield from export.auto_register(register)
     yield from helper.auto_register(register)
 
     if register and config.get('INTERFACE_TOGGLE'):
-        OP_interface_toggle.toggle(True)
+        OGRE_OP_interface_toggle.toggle(True)
 
 """
 General purpose ui elements
@@ -120,20 +129,6 @@ def draw(self, context):
         #    row = layout.row(align=True)
         #    op = row.operator( 'jmonkey.preview', text='', icon='MONKEY' )
 
-        # TODO
-        #if _USE_TUNDRA_:
-        #    row = layout.row(align=True)
-        #    op = row.operator( 'tundra.preview', text='', icon='WORLD' )
-        #    if TundraSingleton:
-        #        op = row.operator( 'tundra.preview', text='', icon='META_CUBE' )
-        #        op.EX_SCENE = False
-        #        if not TundraSingleton.physics:
-        #            op = row.operator( 'tundra.start_physics', text='', icon='PLAY' )
-        #        else:
-        #            op = row.operator( 'tundra.stop_physics', text='', icon='PAUSE' )
-        #        op = row.operator( 'tundra.toggle_physics_debug', text='', icon='MOD_PHYSICS' )
-        #        op = row.operator( 'tundra.exit', text='', icon='CANCEL' )
-
         add_preview_button(self, context)
 
         #row = layout.row(align=True)

io_ogre/ui/helper.py

@@ -62,10 +62,6 @@ class OGRE_MT_ogredoc_Installing( OGRE_MT_ogre_helper ):
 
         4. Install an mesh viewer (OgreMeshViewer or OgreMeshy)
             * If your using 64bit Windows, put OgreMeshy to C:\\OgreMeshy
-
-        5. realXtend Tundra
-            * For latest Tundra releases see http://code.google.com/p/realxtend-naali/downloads/list
-              - You may need to tweak the config to tell your Tundra path or install to C:\Tundra2
 """
 
 @ogredoc
@@ -148,12 +144,5 @@ class OGRE_MT_ogredoc_Bugs( OGRE_MT_ogre_helper ):
         (Any modifier that changes the vertex count is bad with shape anim or armature anim)
     . never rename the nodes created by enabling Ogre-Material-Layers
     . never rename collision proxy meshes created by the Collision Panel
-    . lighting in Tundra is not excatly the same as in Blender
-Tundra Streaming:
-    . only supports streaming transform of up to 10 objects selected objects
-    . the 3D view must be shown at the time you open Tundra
-    . the same 3D view must be visible to stream data to Tundra
-    . only position and scale are updated, a bug on the Tundra side prevents rotation update
-    . animation playback is broken if you rename your NLA strips after opening Tundra
 '''
 

io_ogre/unused.py

@@ -172,7 +172,6 @@ def poll(cls, context):
         if context.active_object: return True
 
     def invoke(self, context, event):
-        global TundraSingleton
         path = '/tmp/preview.scene'
         self.ogre_export( path, context )
         JmonkeyPipe( path )