pypos3d 2.5.1

Wavefront files and Poser files manipulation library

    This file is the README of the library pypos3d.
    
    # 1) INTRODUCTION:
    
    This library is a port of the old DATA3D library of the OpenSource Pojamas project.
    I own both of them.
    
    pypos3d aims to replace Pojamas.DATA3D library with a very close interface.
    Application ePOSER (in Eclipse RCP) is replaced by a new MMI concept based on 
    LibreOffice/Python.
    
    This Python library intends to give high level operations for some 3D files:
    - WaveFront Files (.OBJ and compressed .obz [gziped]): 
      * Read / Write
      * Groups manupilation : add, remove, optimization, fusion
      * UV texture maps creation and modification
      * High level method:
        Plane Split, Plane Slice, Remesh, Hole filling, untriangularization
    
      All Wavefront functions (classes) are in the pypos3d.wftk package
    
    - Poser Files (.PZ3, .CR2, .PZZ, .CRZ, .PP2, .PPZ, .HR2, .HRZ):
      * Read / Write
      * Actors, Props, Cameras, ... manipulations\: add, remove, rename
      * Morph report and morph report on alternate geometries
      * Cleaning
      * Character creation
      
      All Poser functions (classes) are in the pypos3d.pftk packages
    
    Initialy, Pojamas project was a Eclipse RCP application based on a SWT/Java3D MMI. 
    For maintenance reason, this RCP application will be discontinued and shall be replaced
    by another one (cf. chapter 4 'GUI').
    
    #2) INSTALLATION:
    
    ##2.1) Library Installation:
    The library shall be installed with pip:
    `> python3 -m pip --user pypos3d`
    
    ##2.2) GUI Install:
    
      First, download the relevant GUI distribution package from Source Forge: https://sourceforge.net/projects/pojamas/files/
         Filename : PyPos3DLO-X.Y.Z.zip
      Unzip it in your usual work directory (anywhere, in fact)
    
      1. On _Linux_ (and probably Mac - To Be Confirmed):
         Install first the library and its dependencies
         Launch the GUI installer\: PyPos3D-App-Installer.ods
         Clic on **Check** install first and then on **Install**
         Close LibreOffice
    
         The installation is finished, you can use the PyPos3DLO.ods computation sheet
         
         For Debian >11, you could have to add support of python to LibreOffice with the following package:
         apt-get install libreoffice-script-provider-python
    
         in the pip tab of the installer authorize: --break-system-packages
    
      2. On _Windows_ (and for pure LibreOffice Installation on Linux)
         You will need to extend the internal Python installation with the dependencies.
         The PyPos3dLO installer will help you.
    
         Launch the GUI installer : PyPos3D-App-Installer.ods
         Clic on **Check** install first and then on **Install**
         Close LibreOffice
         
         In case of failure, you could need to visit the 'pip' tab of the file PyPos3D-App-Installer.ods
         This tab provides the means to check pip status on your platform and to install or upgrade it if needed.
         
         Important notice\:
         On windows the current working directory is the installation directory of libreoffice (event if you double-click on a file somewhere).
         So, if you need to install pip with the 'Get pip boot' option, you will have to choose a writable destination file for the downloaded module. 
         For example C:\\Users\\olivier\\Documents\\get-pip.py
         
         Then, after a click on 'Install Boot Pip', the results are like\:
         
         **Install stdout**	
         Defaulting to user installation because normal site-packages is not writeable 
         Collecting pip   
         Downloading pip-25.0.1-py3-none-any.whl.metadata (3.7 kB) Collecting setuptools   
         Downloading setuptools-77.0.3-py3-none-any.whl.metadata (6.6 kB) 
         Collecting wheel   
         Downloading wheel-0.45.1-py3-none-any.whl.metadata (2.3 kB) 
         Downloading pip-25.0.1-py3-none-any.whl (1.8 MB)    ---------------------------------------- 1.8/1.8 MB 1.2 MB/s eta 0:00:00 
         Downloading setuptools-77.0.3-py3-none-any.whl (1.3 MB)    ---------------------------------------- 1.3/1.3 MB 1.2 MB/s eta 0:00:00 
         Downloading wheel-0.45.1-py3-none-any.whl (72 kB) 
         Installing collected packages: wheel, setuptools, pip Successfully installed pip-25.0.1 setuptools-77.0.3 wheel-0.45.1 
         
         
         **Install stderr**	  
         WARNING: The script wheel.exe is installed in 'C:\Users\olivier\AppData\Roaming\Python\Python310\Scripts' which is not on PATH.   
         Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.   
         WARNING: The scripts pip.exe, pip3.10.exe and pip3.exe are installed in 'C:\Users\olivier\AppData\Roaming\Python\Python310\Scripts' which is not on PATH.   
         Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location. 
         
         Both warning are  __not relevant__  for pypos3d usage
         
    
         The installation is finished, you can use the PyPos3DLO.ods sheet as an algorithm launcher.
         
         
    	 __deprecated mention__
    	 As of May-2021, a **limitation** has appeared on Windows 10 / LibreOffice both 6.4 and >7 using Python 3.7
    	 pip 21 is  does not run anymore under LibreOffice 
    	 Workaround: Install Python 3.7 on Windows and install pypos3dv manualy
    
    
      3. Manual Install:
         Check which version is used (or brought) by LibreOffice
         First, try to Install the 3D viewer (if it works, it will bring all dependencies)\:
         `> python3 -m pip --user pypos3dv`
    
         In case of pypos3dv trouble, Install the _only_ library:
         `> python3 -m pip --user pypos3d`
         
         From the previously unzipped GUI package:
         copy pypos3dapp.py and pyposinstaller.py files in your LibreOffice Python's scripts directory (create it if needed)
    	On Linux:   $HOME/.config/libreoffice/4/user/Scripts/python/
    	On Windows: C:\Users\olivier\AppData\Roaming\Python\Python310
    
        That's all, you can use the PyPos3DLO.ods computation sheet
    
    
    ##2.3) 3D OpenGL Viewer Install:
    The Viewer shall be installed with pip:
    `> python3 -m pip --user pypos3dv`
    
    According to your system install, you may have to install some libraries:
    Pillow (>= 6.2)
    glfw (>=3)
    
    On Debian 10 (i386)
      glfw can't find the glfw3 library, because of the installation path
      `apt-get install libglfw3`
      `export PYGLFW_LIBRARY=/lib/i386-linux-gnu/libglfw.so.3`
    
    
    
    #3) DESIGN:
    The pypos3d Library has the following structure:
      * langutil: A personal generic package for some utilities
    
      * pypos3d.wftk: WaveFront manipulation package
        The main classes are pypos3d.wftk.WaveGeom and pypos3d.wftk.GeomGroup.
        Refer to WaveGeom documention for information
    
      * pypos3d.pftk: Poser files manipulation package
    
      * pypos3d.propslim: Decimation function (port of Michael Garland "SlimKit Surface Modeling Tools")
    
      * Dependencies:
        - numpy
        - scipy
        - xlrd
        - Pillow
    
    The pypod3dv Viewer package has a flat structure:
      * Modules: Window.py and Renderable.py
      * Launcher: pypos3dv (executes __main__.py)
    
      * Dependencies:
        - pypos3d
        - Pillow
        - PyOpenGL
        - PyGLM
        - GLFW
    
    
    #4) TESTS:
    This library is tested with unitest with a target coverage rate over 90%.
    Unit tests are delivered in another package: pypos3dtu
    Coding rules are based on CNES (RNC-CNES-Q-HB-80-535) - CNES is the French National Space Agency https://www.cnes.fr -
    
    Installation and commissionning tests are performed on:
    - AlmaLinux 9           Python 3.9   LibreOffice 7.1
    - AlmaLinux 9           Python 3.12  LibreOffice 7.1
    - CentOS 8, 7           Python 3.6   LibreOffice 6.4 : Deprecated
    - Fedora >34            Python 3.10  LibreOffice 7.2
    - Debian 10 (i386)      Python 3.7   LibreOffice 7.0 : Deprecated
    - Debian 11             Python 3.9   LibreOffice 7.1 : Deprecated
    - Debian 12 (i386)      Python 3.11  LibreOffice 7.4
    - Ubuntu 25.10		    Python 3.13  LibreOffice 25.8
    - Microsoft Windows 11  Python 3.10  LibreOffice 25.8
    
    #5) GUI:
    As mentioned previously, the former Pojamas application was an Eclipse RCP (obsolete RCP3).
    For tests purpose, a LibreOffice calc based GUI is proposed.
    The GUI requires LibreOffice >= 6.4 on Windows and LibreOffice >= 6.3 on Linux (CentOS > 7)
    
    This version of the library provides a simple 3d Viewer (cf. pypo3dv)
    
    #6) LIMITATIONS:
    pypos3d read/write operations have been validated on Poser9, Poser11 and with Poser12
    Nevertheless, some new features in Poser11/Poser12 or Poser13 may generate mis-interpretation 
    
    #LICENCE:
    This library is delivered under the BSD license.
    
    
    KR, Olivier
    
    
    ------------
    
    #Dev Notes
    
    Add a View on Poser File
    Extract WFMat from Poser File
    - Options
    
    Add a View in Edit Sheet
      * File (scene, character(s), prop(s))
      * Character
      * Prop
      * Actor
      * Channel
    
    Add a Menu to the viewer
      - Hide/Show parts (groups)
      - Move parts
      - Rotate parts
    
    For actors :
    + Add 'puton:FACE' for translation/rotation