Merge branch 'main' of https://github.com/munkybutt/SkinPlusPlus

.github/workflows/codeql.yml

@@ -0,0 +1,91 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '34 0 * * 2'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners
+    # Consider using larger runners for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: c-cpp
+          build-mode: autobuild
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - if: matrix.build-mode == 'manual'
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

README.md

@@ -59,24 +59,38 @@ This software (SkinPlusPlus) is provided "as is", without any warranty. The auth
     - 2022 - Python37
 
 ## Usage
-There are three types of data that are of interest when working with skin data:
-- vertex bone weights (float)
+`PySkinData` is a c++ struct exposed to Python as the class `SkinData`.
+This struct contains five separate data attributes:
+- bone names (str)
+- vertex bone weights (float64)
 - vertex bone ids (int)
-- vertex positions (float)
+- vertex positions (float64)
+- vertex indices (int)
 
-PySkinData is a c++ struct containing the above data, exposed to python as the SkinData class.  
-This struct allows the data to be typed correctly rather than all typed as floats.  
-On the c++ side, the data is stored in Eigen matrices.  
-On the Python side, the data is exposed via Pybind11 as numpy arrays.
+This struct allows the data to be typed correctly.
+The c++ backend uses Eigen matrices and exposes them to Python via Pybind11 as numpy arrays.
 
 Due to the relationship between Eigen and Pybind11, there is no performance hit when passing arrays to and from c++.
 
-🔥 It is fast 🔥
+This results in a reduction in the number of iterable structures the data needs to be stored in to convert back and forth btween numpy and the c++ SDK get and set weight functions.
 
-It also provides a simple interface to the raw data in the form of the following properties:
-- SkinData.weights
-- SkinData.bone_ids
-- SkinData.positions
+🔥 This means it is fast 🔥
+
+Take 3DsMax as an example, to get from a numpy ndarray to 3DsMax SDK Tab it requires the following steps:
+- ndarray -(copy)-> py list -(copy)-> mxs Array -(copy)-> Tab -> set weights.
+
+Compared to the SkinPlusPlus approach:
+- ndarray -(reference)-> Eigen Matrix -(copy)-> Tab -> set weights.
+
+The native approach runs multiple copy operations in python before passing the data to c++.
+SkinPlusPlus has no copy operations in Python.
+
+`SkinData` provides attribute access to the raw data with the following properties:
+- `SkinData.bone_names`
+- `SkinData.weights`
+- `SkinData.bone_ids`
+- `SkinData.positions`
+- `SkinData.vertex_ids`
 
 ## Performance
 Performance benchmarks are done on a mesh with 507,906 vertices, each with 6 influences.