niftools/blender_niftools_addon

The Blender Niftools Addon is a Blender add-on to enable import and export of NetImmese File Formats including .nif, .kf, .egm.

niftools.github.io

Installing Locally

Prerequisites

You need to install Ruby. After you install Ruby you can simply install Bundler: gem install bundler

Then to get the necessary gems for the site you run bundle install from the project root.

You will most likely get an SSL error while trying to build so you need to grab http://curl.haxx.se/ca/cacert.pem then install it anywhere (e.g. Ruby folder) and add it to your PATH.

OPTIONAL If you want to edit or create posts more easily (instead of by hand), you can uncomment - jekyll-admin in _config.yml to use the admin interface at localhost:4000/admin. This change does not need to be committed as jekyll-admin is local only. I would recommend leaving it otherwise commented as it appears to disable file watching while editing the site design.

OPTIONAL If you are ever designing new pages and need to change \bower_components in order to add package dependencies you will need to install Node.js/npm. You must then install Bower with npm install -g bower. From there you can add Bower packages to the project root's bower.json and then run bower install or you can run bower install <package>.

Building and Running

To build the site locally you run jekyll build. To serve the site locally you can run jekyll serve. This will serve from localhost:4000 and will watch for any changed files so that changes will show up as you make them.

To view what the site would look like with the posts in _drafts published you can run jekyll serve --drafts.

Front-Matter

Jekyll will parse any file with front matter at the very beginning of the file. Empty front matter looks like so:

   ---
   ---

You can also include the following variables:

Variable	Description	Format
layout:	Which template to choose in _layouts.	default, page, post
title:	Text which shows in the webpage title and also the jumbotron	<string>
date:	Used to sort a post in chronological order. Also used in feed.xml.	YYYY-MM-DD HH:MM:SS +/-TTTT
category:	What category your post belongs in.	<string>
categories:	What categories your post belongs in.	[<string>, ...]
tags:	A list of tags relevant to the post.	[<string>, ...]
excerpt:	Text which shows in the page meta description. If used in a post it will act as the synopsis on the front page.	<string>
subtitle:	Text which shows under the title in the jumbotron.	<string>
menu:	Which navbar item is to have the class selected	<string>
toc:	Whether this page should have an auto-generated table of contents.	true | false
geopattern:	A custom string input for the jumbotron SVG background. Otherwise it uses title:	<string>
navbar:	Used to override the navbar style for this page.	navbar-inverse navbar-inversed
css:	Custom CSS to include on this page. Must install to /assets/css/ but only list the filename.	[<string>, ...]
js:	Custom JS to include on this page. Must install to /assets/js/ but only list the filename.	[<string>, ...]

A common example of front matter for a post would be

---
layout: post
title:  "Example Post"
date:   2017-05-10 13:25:35 +0200
categories: nifskope releases
---

Publishing

To avoid publishing manually, you may use jekyll-admin if you have uncommented it in _config.yml and restarted jekyll. The admin interface will be available at localhost:4000/admin. You can include custom front matter variables in the field below the post text.

Posts

Placing any Markdown or HTML file in _posts with valid front matter will publish the file to the site. Where it goes will depend on the front matter such as the layout and what categories are listed. A post layout with categories: nifskope releases will get published to /nifskope/releases/.

Relevant Documentation

Categories

Most posts should likely consist of two categories: the project or main product name and a subcategory such as releases e.g. categories: nifskope releases or categories: blender releases. If posting about general developmental news or about multiple projects, use something like category: updates.

Pages

A page layout titled mypage.md will get published to /mypage if it is in the project root.

Relevant Documentation

blender_niftools_addon's Issues

Sub Issue : #22 : Test : UV Layer Mapping

Write a test to check when a user has failed to set the UV layer.

Ref Summary Issue #22

Invert Scale Correction

The Scale factor is inverted. Importing with a scale correction of 10 results in the object being 10x smaller rather than 10x larger.

Sub Issue : #26 : Refactor Texture code from Material Module

Move texture creation code from Material module to the Texture Module.

Ref Summary #26

browse button for adding keyframe or face gen files cannot be used

Blender doesn't support opening separate file browser instances. once the import function begins the box to add the keyframe or the facegen file can not be utilized unless the file path is manually input.

One option is to set the nif file in the same manner as the kf and egm files in a selection box then have a final execution button to begin the actual importing.

Summary : Refactor Material System : Texture/Geometry

Material system is forcing requirement that a material be set.

If none is provided data that is available willl not be exported, normal, vertex color.
UV has additional requirement that texture be present.

There are certain use cases where you might want to export an object and not have the associating texture/material data.

Sub Issue : # 16: Bone export missing translation data

Exported bones have do not have correct values for their location data on export. All values are set to zero. Rotation values seem to be intact so need to investigate the Matrix decomposition.

Installer and MakeZip scripts for Windows not working

@amorilia Various bugs have been observed when running makezip and install bat scripts

• On xp need to wrap path in String quotes to avoid problems with spaces in path.
• Missing pyffi pararmetres
• nif.xml was not packaged when run on win 7.

@Ghostwalker71 - Currently working on a path for buildenv to detect 7zip

Sub Issue : #84 : Create a Capsule Primitive for use with Collisions

Currently a cylinder is the closest representation to the meta-capsule shape that is used create a bhkCapsuleShape. Adding our own custom primitive will allow us to both visually represent the shape due to lack of viewport visualisation internally with Blender and gives us control to ensure the shape is easier to read data from.

Note: Investigate current Bullet integration roadmap and see its affect on collision system in terms of collision bounds in general.

Ref: #84

properly bundle pyffi for blender

Currently we bundle pyffi as a submodule of io_scene_nif. This is broken, because pyffi uses absolute imports all over the place. Note that absolute import is recommended:

http://stackoverflow.com/questions/4209641/absolute-vs-explicit-relative-import-of-python-module
http://www.python.org/dev/peps/pep-0008/#imports

Looking at the code, switching to relative imports in pyffi isn't really an option as it will lead to an unreadable import mess.

Some options:

1. Should we bundle pyffi instead under scripts/addons/modules after all, so absolute import works? (Additional complication: this is broken under blender 2.62,).
2. Should we release pyffi also as a separate blender addon?

Perhaps we have to ask the blender devs for suggestions to solve this problem?

(Also, making note of another unrelated question: what will the blender addon installer do on upgrades? Will it clean up all folders it writes to first?)

Summary : Skeletal Sub-System

Update the sub-sustem to the new API.

Map only used Collision Types to UI

In the Niftools Panel we map our bhkShape types to Blender Collision types. Currently there are additional types, eg. cylinder/capule. With the Bullet Physics Engine soon to be integrated, we should provide a mechanism to select only the Blender collision types that best suit our needs.

User/Author info Panel

Add a panel which allows users to add athurship. Map this to user_info. Add regression test in feature/object

UV layer detection

Failure to set the which UV layer to map to result in an empty string querying the dict. This causes the script to stop executing as there is no layer with an empty string as name.

Desired behaviour is to inform user they have failed to set the layer mapping and inform them which object this problem has occured on.

Billboard Support

Add Support to use billboard node via a camera tracking constraint.

Sub Issue : #14: Test : Add pycode collision generation.

We need to update the Collision tests to generate their collision objects via python code. As in reflection to the new Geometry tests @neomonkeus has been working on.

Sub Issue : #26 : Separate UV import/export from Material code

Geometry based tests fail due to requirement that a material must exist for the data be added to the geometry.
See issue #22 for summary

Code requires a material to execute geometry code related to uv data generation; uv_sets,

Results in no uv data being generated without material present.

Ref Summary #26

Add support for texture transforms

Import & export ignore texture transforms. Blender already has most of these properties in the texture influence sections, so it will be just a case of connecting them as needed.

Specifically, an NiSourceTexture has a property called has_transform. This allows for texture offsets and other options.

Windows installer installs files in wrong location.

Making a note here to remind ourselves to fix this in the nsi script. It looks like SetOutPath is missing for a large number of files.

Issue: Matrix tranformation not being applied on export

Test framework has caught the following integration regression test failure:

blender_nif_plugin\testframework\test\geometry\trishape\n_gen_geometry.py 
line 239, in n_check_transform

nose.tools.assert_equal(n_trishape.translation.as_tuple(),(20.0, 20.0, 20.0)) # location
AssertionError: AssertionError: Tuples differ: (0.0, 0.0, 0.0) != (20.0, 20.0, 20.0)

This has been manually tested with a non-testframework nif to ensure that the problem is not internally generated. This only affects the export side.

Initial action; look through commit log and see what code has been changed on export side to see if cause can be found as test passed previously. Investigate matrix transformations code, remote debugging if necessary.

Format Version to Game Mapping.

A user should be able to select a Nif Format version, which will in-turn provide a selection of possible supported games types for that version.

The selected "Game" is used to determine code execution, returning "Game" specific types. Currently, the "Game" is selected as the highest version. The code does not check if "Game" in Version

Sample Error: Selecting 20.0.0.4 for export, with .kf animation even though the game_list contains OB, CIV4, both of which support .kf's.

Use case for supporting specific version, rather than forcing highest supported version to be mapped to a particular game is that although we treat the "Game" as being for one physical game, other games may also use the same version information.

Combine Shapes Option Causes Crash

Importing a nif with the Combine Shapes options enabled will cause Blender to crash when entering Edit Mode.

Sub Issue : # 16: Incorrect encoding of bone names

Each bone is having the binary b' concatinated to the string at some point, so instead of b' Bip 01 being encoded, the result is b' b' Bip 01. This causes alot of the code to fail as these are used as dictionary keys for lookup.

Introduce Version filtering options

Reconbobulate a system that allows filtering of UI data based on version criteria.

Currently options that are externalised like enums,etc, pull all data from multiple versions. The user is presented with information that is not relevant to the version that they maybe working on. eg HAVOK MATERIAL will contain data for OB, FO3, SKY.

Add filter and version selection system.

Add Pyffi as a sub-module

Including pyffi as a sub-module within the plug-in code will enable the Blender Plug-in to be installed uniformly by consolidated updated into a single packageable add-on.

Havok : Radius calculation : Collision padding

Many of the radius import and export values are incorrect, either not calculated on import or export or the algorithm used to calculate them is incorrect..

The general case is use of bounds box converted to a sphere bounds, but the sphere encompassed by the box, not the other way around which lead to radius = box.lenght rather radius = abs(max(vertexlist)

Sub Issue : #84 :Collision code for BhkCapsule is incomplete

Additional work on the code used to calculate the values for a bhkcylinder is required.

Ref: #84

Sub Issue : #84 : Collision system expansion

Investigate mapping additional properties into blender collision system.

Ref: #84

Expand .blend generation.

Add option to generate each of the blend files for the import_export & export_import functions.

Vertex Alpha Prop Support

Finish implementing vertex Alpha support.

Vertex list bloating

Vertex list bloats when a material,uv or weights are added.

Issue: Normal direction inverted on export

User reported issue - KWITS

I am having a very unusual problem with Normals. Everything appears perfect in 2.62 but after exporting and viewed in NIFScope, the textures for my mesh are on the inside. It appears the Normals are flipped.

Initial investigation did not show the problem, due to an issue with NifSkope ignoring the face normal direction.

Manual inspection of normals does show that there is negated values, but further investigation is required as cannot rely on NifSkope.

The problem seems to be isolated to the export side, but unless there is some concrete assertions then it maybe that the import code is recalculating the normals either explicitly through the code or by Blender updates. The mesh.recalc function does not always work as desired if faces are internal to the mesh, eg -bowl.

Remove importing of tests.

Importing any Test will cause that test to be re-run. Remove inheritance coupling to avoid this problem and allow for general reuse of code.

Summary : Geometry Tests

Create a subset of tests for the test framework specifically for geometry based data.

Summary : Texture System

Refactor the code to support texture import and export

Summary : Collision System

Summary Issue used to track all collsion related issues.

BhkShape Object representation

Investigate representing the various bhktransform shapes as objects/empties. There are number of nodes which have their transforms combined and applied to the collision object such as bhkRigidBodyT, bhkConvexTransformShape.

Default scale correction should be 10.

Scale correction should default to 10, not 1, or we get huge imports. Obviously this needs fixing of the tests as well.

Summary : Texture Tests

Create tests to support current texture code system to ensure that it works for import & export and support future updates.

Ref #13

Sub Issue : #26 : Separate Normal data from Material code

Code requires a material to execute geometry code related to normal data generation; normal, tangent, bi-tangent.
This results in no normal data being generated

Ref Summary #26

Causes Geometry based tests fail due to requirement that material be added to the geometry.
See issue #22 for summary

Summary : Collison Tests

Create a subset of tests for the test framework which test the supported Bhk-based collision nodes.

Update to BMesh API

Update to the code to use the BMesh API for Blender 2.63+

Vertex Color Import Layer creation

On import, vertex colors are imported to a Vertex Color Layer. Only one Vertex Color Layer should being created per object to support RGB values, future support will add second layer as an Alpha channel, in greyscale, due to limitations with Blender.

The issue arises that multiple layers are being generated on import.

Allow selection/setting of default import/export values

Increase code coverage by allowing different setting for import & import.
This will also be required as for tests which require specific options to be set for correct import/export eg. armature systems etc.

Duplicate vertex deletion

Allow the user to select if vertex deletion should occur and the detection range. Currently code has not been ported to use the new API. In the 2.4x version deletion occured automatically. There maybe instances where the user might want to not deleted duplicate verts or increase the range of duplicate detection due to artifacts of the merge process.

Summary: Unit Tests

Expand the TestFramework to do Unit Test level testing.

Currently we do integration level testing on a feature basis, which test independant features. It would be good to add class & method level testing during the refactoring process. This will help improve on code quality and test coverage.

Path transformation Engine

Many games use relative pathing. Create a system that will load relative paths by allowing the user to define root folders, relative mesh and texture folders, which get used on import/export. This will masking of the details from the user.

This can also be expanded to a per version system, which would be applicable in cases where conventions maybe used.

Summary : Material Tests

Create a subset of tests for the test framework which test the supported material properties.

Bpy.type.HavokMaterial based collision and Sub-Shape Support

Currently the scripts work by add the havok_material as a property.
We can utilitse the existing material system and create a HAVOK_MATERIAL set of bpy.types.Materials.
This would create a more flexible collision system which can then generate Sub-Shapes and Mult-Material Mopps.

NiAlphaProperty detection for Textures

We need to add support to detect alpha channels in textures. The problem is that some texture use the alpha channel for other purposes.

BhkShape.radius

Figure out how the radius should be calculated.

The current code has has the following (6 * self.HavokScale) multiplication of the largest absolute value of vertex values. This is used to set the b_obj.game.radius for new objects. This formula should be checked to see if it holds for vanilla assets as other calculations ignore this value.

Perhaps a new dedicated value should be used instead. See #88 for further thoughts on this.

The value should also be checked on import/export value in case it is a nif which was imported with an incorrect value. It should be recalculated and compared to ensure correctness.