automatic import of python-indexmapping

3 files changed, 1134 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index e69de29..9291bff 100644
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1 @@
+/IndexMapping-1.0.2.tar.gz
diff --git a/python-indexmapping.spec b/python-indexmapping.spec
new file mode 100644
index 0000000..d883db0
--- /dev/null
+++ b/python-indexmapping.spec
@@ -0,0 +1,1132 @@
+%global _empty_manifest_terminate_build 0
+Name:		python-IndexMapping
+Version:	1.0.2
+Release:	1
+Summary:	1D array transpose/conversion
+License:	MIT
+URL:		https://github.com/yoyoberenguer/IndexMapping
+Source0:	https://mirrors.nju.edu.cn/pypi/web/packages/0d/4f/e88c1b2373cfde3020fb6b6e3a535c73ddf5d7597fa8b1b0574bba0ee882/IndexMapping-1.0.2.tar.gz
+
+Requires:	python3-setuptools
+Requires:	python3-Cython
+
+%description
+# IndexMapping 
+
+This library contains tools that helps indexing arrays from 
+`1d array` (C buffer data type) to 3d array and reciprocally.
+The functions `to1d` and `to3d` are complementary and can be
+resume with the following statment :
+```
+If we know the index value of a buffer (index), find the 
+equivalent position in a 3d array (x, y, z) and reciprocally; 
+such as :
+```
+
+- `to3d` buffer[index]     --> 3d array[x, y, z]
+- `to1d` 3d array[x, y, z] --> buffer[index]
+
+`to1d & to3d` can also be used to convert 1d array -> 3d array
+and vice versa. The library also includes functions to transpose
+C buffer data type like the numpy transpose function used for 
+multi-dimensional arrays.
+
+How can we transpose row and columns in a 1d array since 
+a buffer is a contiguous or non-contiguous adjacent set of data?
+
+1) reshape the 1d array to a 3d equivalent format 
+2) swap row and column of the equivalent 3d array (transposed) 
+3) Convert the 3d array back to 1d array type (flatten)
+
+This library provide functions such as` vfb_rgb` & `vfb_rgba` 
+(for transparency) to transpose the array directly.
+
+```
+Below a good example with 9 pixels buffer:
+// Original 9 pixels buffer (length = 27), pixel format RGB 
+(contiguous values)
+buffer = [RGB1, RGB2, *RGB3, RGB4, RGB5, RGB6, RGB7, RGB8, 
+RGB9]
+
+Equivalent reshape model (w, h, depth) would be (3x3x3):
+3d model = [RGB1 RGB2 *RGB3*]
+           [RGB4 RGB5  RGB6 ]
+           [RGB7 RGB8  RGB9 ]
+
+// Same 1d buffer after transposing the values (swapped 
+row and column)
+buffer = [RGB1, RGB4, *RGB7*, RGB2, RGB5, RGB8, RGB3, RGB6, 
+RGB9]
+
+Equivalent reshape model (w, h, depth) after transposing the
+original buffer
+3D model = [RGB1, RGB4, RGB7]
+           [RGB2, RGB5, RGB8]
+           [RGB3, RGB6, RGB9]
+```
+After transposing the buffer we can observed that the 3d 
+equivalent model is an array with `row & columns swapped`. 
+This operation would be identical to a numpy transpose 
+function such as : 3darray `transpose(1, 0, 2)`
+
+
+
+
+## Installation 
+```
+pip install Mapping
+```
+
+## Methods
+```` cython
+# MAP BUFFER INDEX VALUE INTO 3D INDEXING
+cpdef tuple to3d(unsigned int index, unsigned int width, unsigned short int depth):
+   
+    use_pygments=false
+    """
+    Index mapping (buffer indexing --> 3d array)
+    
+    :param index : python int; buffer index    
+    :param width : python int; width (3d array columns number) 
+    :param depth : python int; depth (RGB = 3) | (RGBA = 4) 
+    :return      : Return a python tuple containing x, y, z index values 
+    """
+    
+    cdef xyz v = to3d_c(index, width, depth)
+    return v.x, v.y, v.z
+````
+
+
+``` cython
+# MAP 3D INDEX VALUE INTO BUFFER INDEXING
+cpdef unsigned int to1d(unsigned int x, unsigned int y, unsigned int z, unsigned int width, unsigned short int depth):
+    
+    use_pygments=false
+    """
+    Index mapping (3d array indexing --> buffer)
+    
+    :param x     : python int; index x of the array 
+    :param y     : python int; index y of the array 
+    :param z     : python int; index z of the array 
+    :param width : python int; width of the 3d array (number of columns)
+    :param depth : python int; depth, either RGB (depth = 3) or RGBA (depth = 4)
+    :return      : python int; return the index value (1d array)
+     corresponding to a 3d array with index position  (x, y, z) 
+    """
+    return to1d_c(x, y, z, width, depth)
+```
+``` cython
+# VERTICALLY FLIP A SINGLE BUFFER VALUE
+cpdef vmap_buffer(unsigned int index, unsigned int width, unsigned int height, unsigned short int depth):
+                  
+    use_pygments=false
+    """
+    Vertically flipped a single buffer value.
+
+    Flip a C-buffer value vertically
+    Re-sample a buffer value in order to swap rows and columns of
+    its equivalent 3d model
+
+    :param index  : integer; index value to convert  
+    :param width  : integer; Original image width 
+    :param height : integer; Original image height   
+    :param depth  : integer; Original image depth=3 for RGB or 4 for RGBA
+    :return       : integer value pointing to the pixel in
+     the buffer (traversed vertically). 
+    """
+    return vmap_buffer_c(index, width, height, depth)
+```
+
+``` cython
+# FLIP VERTICALLY A BUFFER (TYPE RGB)
+cpdef np.ndarray[np.uint8_t, ndim=1] vfb_rgb(unsigned char [:] source, unsigned char [:] target,
+        int width, int height):
+     
+    use_pygments=false
+    """
+    Vertically flipped buffer containing any format of RGB colors
+    
+    :param source   : 1d buffer to flip vertically (unsigned char 
+    values). The array length is known with (width * height *
+    depth). The buffer represent  image 's pixels RGB.      
+    :param target   : Target buffer must have same length than source  buffer)
+    :param width    : integer; Source array's width (image width). 
+    :param height   : integer; source array's height (image width). 
+    :return         : Return a vertically flipped 1D RGB buffer 
+    (swapped rows and columns of the 2d model) 
+    
+    """
+    return numpy.asarray(vfb_rgb_c(source, target, width, height))
+```
+``` cython
+# FLIP VERTICALLY A BUFFER (TYPE RGBA)
+cpdef np.ndarray[np.uint8_t, ndim=1] vfb_rgba(unsigned char [:] source, unsigned char [:] target,
+        int width, int height):
+        
+    use_pygments=false
+    """
+    Vertically flipped buffer containing any format of RGBA colors
+        
+    :param source   : 1d buffer to flip vertically (unsigned 
+    char values). The array length is known with (width * height
+     * depth). The buffer represent image 's pixels RGBA.     
+    :param target   : Target buffer must have same length than source buffer)
+    :param width    : integer; Source array's width (image width)
+    :param height   : integer; source array's height (image height)
+    :return         : Return a vertically flipped 1D RGBA buffer 
+    (swapped rows and columns of the 2d model) 
+    """
+    return numpy.asarray(vfb_rgba_c(source, target, width, height))
+
+```
+
+``` cython
+#  FLIP VERTICALLY A BUFFER (TYPE ALPHA, (WIDTH, HEIGHT))
+cpdef unsigned char [::1] vfb(unsigned char [:] source, unsigned char [::1] target, int width,
+    int height):
+    
+    use_pygments=false
+    """
+    Flip vertically the content (e.g alpha values) of an 1d buffer
+    structure. buffer representing an array type (w, h) 
+
+    :param source : 1d buffer created from array type(w, h) 
+    :param target : 1d buffer numpy.empty(ax_ * ay_, dtype=numpy.uint8) 
+    that will be the equivalentof the source array but flipped vertically 
+    :param width  : source width. 
+    :param height : source height. 
+    :return       : return 1d buffer (source array flipped)
+    """
+    return vfb_c(source, target, width, height)
+```   
+
+``` python
+EXAMPLE :
+
+import IndexMapping
+from IndexMapping.mapping import to1d
+import pygame
+import numpy
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+w, h = background.get_size()
+rgb_array = pygame.surfarray.pixels3d(background)
+c_buffer = numpy.empty(w * h * 3, dtype=numpy.uint8)
+
+# Convert 3d array (rgb_array) into a C buffer (1d)
+for i in range(w):
+    for j in range(h):
+        for k in range(3):
+            index = to1d(i, j, k, w, 3)
+            c_buffer[index] = rgb_array[i, j, k]       
+```
+
+```python
+
+import IndexMapping
+from IndexMapping.mapping import to3d
+import pygame
+from pygame.surfarray import pixels3d
+import numpy
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+w, h = background.get_size()
+
+rgb_array = pixels3d(background).transpose(1, 0, 2)
+c_buffer = rgb_array.flatten()
+
+length = c_buffer.size
+assert length == w * h * 3, \
+    "C buffer has an incorrect length, got %s instead of %s " \ 
+% (length, w * h * 3)
+
+rgb_array = numpy.zeros((w, h, 3), numpy.uint8)
+        
+# Build a 3d array using the function to3d
+for i in range(length):
+    x, y, z = to3d(i, w, 3)
+    rgb_array[x, y, z] = c_buffer[i]
+```
+```python
+import IndexMapping
+import numpy
+from IndexMapping.mapping import vfb_rgb
+import pygame
+from pygame.surfarray import pixels3d
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+background = pygame.transform.smoothscale(background, (640, 480))
+w, h = background.get_size()
+rgb_array = pixels3d(background)
+
+rgb_buffer = rgb_array.flatten()
+target_buffer = numpy.empty(w * h * 3, numpy.uint8)
+rgb_buffer_transpose = vfb_rgb(rgb_buffer, target_buffer, w, h)
+```
+
+## Building cython code
+```
+If you need to compile the Cython code after any changes in the 
+file Mapping.pyx:
+
+1) open a terminal window
+2) Go in the main project directory where (mapping.pyx & 
+   mapping.pxd files are located)
+3) run : python setup_Mapping.py build_ext --inplace
+
+If you have to compile the code with a specific python 
+version, make sure to reference the right python version 
+in (python38 setup_mapping.py build_ext --inplace)
+
+If the compilation fail, refers to the requirement section and 
+make sure cython and a C-compiler are correctly install on your
+ system.
+- A compiler such visual studio, MSVC, CGYWIN setup correctly on 
+  your system.
+  - a C compiler for windows (Visual Studio, MinGW etc) install 
+  on your system and linked to your windows environment.
+  Note that some adjustment might be needed once a compiler is 
+  install on your system, refer to external documentation or 
+  tutorial in order to setup this process.e.g https://devblogs.
+  microsoft.com/python/unable-to-find-vcvarsall-bat/
+```
+
+## Credit
+Yoann Berenguer 
+
+## Dependencies :
+```
+python >= 3.0
+cython >= 0.28
+```
+
+## License :
+```
+MIT License
+
+Copyright (c) 2019 Yoann Berenguer
+
+Permission is hereby granted, free of charge, to any person 
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without 
+restriction, including without limitation the rights to use, 
+copy, modify, merge, publish, distribute, sublicense, and/or 
+sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following 
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+```
+## Testing: 
+```python
+>>>from IndexMapping.test.test_mapping import run_test
+>>>run_test()
+```
+
+
+## Timing :
+```C:\>python profiling.py```
+
+```
+Testing to1d        per call 2.627551e-07 overall time 0.2627551 for 1000000
+Testing to3d        per call 1.217256e-07 overall time 0.1217255 for 1000000
+Testing vfb_rgb     per call 0.0015129453 overall time 1.5129453 for 1000 --> image 800x800x3
+Testing vmap_buffer per call 1.189032e-07 overall time 0.1189032 for 1000000
+Testing vfb_rgba    per call 0.001878 overall time 1.8783595 for 1000     --> image 800x800x4
+```
+
+
+
+%package -n python3-IndexMapping
+Summary:	1D array transpose/conversion
+Provides:	python-IndexMapping
+BuildRequires:	python3-devel
+BuildRequires:	python3-setuptools
+BuildRequires:	python3-pip
+BuildRequires:	python3-cffi
+BuildRequires:	gcc
+BuildRequires:	gdb
+%description -n python3-IndexMapping
+# IndexMapping 
+
+This library contains tools that helps indexing arrays from 
+`1d array` (C buffer data type) to 3d array and reciprocally.
+The functions `to1d` and `to3d` are complementary and can be
+resume with the following statment :
+```
+If we know the index value of a buffer (index), find the 
+equivalent position in a 3d array (x, y, z) and reciprocally; 
+such as :
+```
+
+- `to3d` buffer[index]     --> 3d array[x, y, z]
+- `to1d` 3d array[x, y, z] --> buffer[index]
+
+`to1d & to3d` can also be used to convert 1d array -> 3d array
+and vice versa. The library also includes functions to transpose
+C buffer data type like the numpy transpose function used for 
+multi-dimensional arrays.
+
+How can we transpose row and columns in a 1d array since 
+a buffer is a contiguous or non-contiguous adjacent set of data?
+
+1) reshape the 1d array to a 3d equivalent format 
+2) swap row and column of the equivalent 3d array (transposed) 
+3) Convert the 3d array back to 1d array type (flatten)
+
+This library provide functions such as` vfb_rgb` & `vfb_rgba` 
+(for transparency) to transpose the array directly.
+
+```
+Below a good example with 9 pixels buffer:
+// Original 9 pixels buffer (length = 27), pixel format RGB 
+(contiguous values)
+buffer = [RGB1, RGB2, *RGB3, RGB4, RGB5, RGB6, RGB7, RGB8, 
+RGB9]
+
+Equivalent reshape model (w, h, depth) would be (3x3x3):
+3d model = [RGB1 RGB2 *RGB3*]
+           [RGB4 RGB5  RGB6 ]
+           [RGB7 RGB8  RGB9 ]
+
+// Same 1d buffer after transposing the values (swapped 
+row and column)
+buffer = [RGB1, RGB4, *RGB7*, RGB2, RGB5, RGB8, RGB3, RGB6, 
+RGB9]
+
+Equivalent reshape model (w, h, depth) after transposing the
+original buffer
+3D model = [RGB1, RGB4, RGB7]
+           [RGB2, RGB5, RGB8]
+           [RGB3, RGB6, RGB9]
+```
+After transposing the buffer we can observed that the 3d 
+equivalent model is an array with `row & columns swapped`. 
+This operation would be identical to a numpy transpose 
+function such as : 3darray `transpose(1, 0, 2)`
+
+
+
+
+## Installation 
+```
+pip install Mapping
+```
+
+## Methods
+```` cython
+# MAP BUFFER INDEX VALUE INTO 3D INDEXING
+cpdef tuple to3d(unsigned int index, unsigned int width, unsigned short int depth):
+   
+    use_pygments=false
+    """
+    Index mapping (buffer indexing --> 3d array)
+    
+    :param index : python int; buffer index    
+    :param width : python int; width (3d array columns number) 
+    :param depth : python int; depth (RGB = 3) | (RGBA = 4) 
+    :return      : Return a python tuple containing x, y, z index values 
+    """
+    
+    cdef xyz v = to3d_c(index, width, depth)
+    return v.x, v.y, v.z
+````
+
+
+``` cython
+# MAP 3D INDEX VALUE INTO BUFFER INDEXING
+cpdef unsigned int to1d(unsigned int x, unsigned int y, unsigned int z, unsigned int width, unsigned short int depth):
+    
+    use_pygments=false
+    """
+    Index mapping (3d array indexing --> buffer)
+    
+    :param x     : python int; index x of the array 
+    :param y     : python int; index y of the array 
+    :param z     : python int; index z of the array 
+    :param width : python int; width of the 3d array (number of columns)
+    :param depth : python int; depth, either RGB (depth = 3) or RGBA (depth = 4)
+    :return      : python int; return the index value (1d array)
+     corresponding to a 3d array with index position  (x, y, z) 
+    """
+    return to1d_c(x, y, z, width, depth)
+```
+``` cython
+# VERTICALLY FLIP A SINGLE BUFFER VALUE
+cpdef vmap_buffer(unsigned int index, unsigned int width, unsigned int height, unsigned short int depth):
+                  
+    use_pygments=false
+    """
+    Vertically flipped a single buffer value.
+
+    Flip a C-buffer value vertically
+    Re-sample a buffer value in order to swap rows and columns of
+    its equivalent 3d model
+
+    :param index  : integer; index value to convert  
+    :param width  : integer; Original image width 
+    :param height : integer; Original image height   
+    :param depth  : integer; Original image depth=3 for RGB or 4 for RGBA
+    :return       : integer value pointing to the pixel in
+     the buffer (traversed vertically). 
+    """
+    return vmap_buffer_c(index, width, height, depth)
+```
+
+``` cython
+# FLIP VERTICALLY A BUFFER (TYPE RGB)
+cpdef np.ndarray[np.uint8_t, ndim=1] vfb_rgb(unsigned char [:] source, unsigned char [:] target,
+        int width, int height):
+     
+    use_pygments=false
+    """
+    Vertically flipped buffer containing any format of RGB colors
+    
+    :param source   : 1d buffer to flip vertically (unsigned char 
+    values). The array length is known with (width * height *
+    depth). The buffer represent  image 's pixels RGB.      
+    :param target   : Target buffer must have same length than source  buffer)
+    :param width    : integer; Source array's width (image width). 
+    :param height   : integer; source array's height (image width). 
+    :return         : Return a vertically flipped 1D RGB buffer 
+    (swapped rows and columns of the 2d model) 
+    
+    """
+    return numpy.asarray(vfb_rgb_c(source, target, width, height))
+```
+``` cython
+# FLIP VERTICALLY A BUFFER (TYPE RGBA)
+cpdef np.ndarray[np.uint8_t, ndim=1] vfb_rgba(unsigned char [:] source, unsigned char [:] target,
+        int width, int height):
+        
+    use_pygments=false
+    """
+    Vertically flipped buffer containing any format of RGBA colors
+        
+    :param source   : 1d buffer to flip vertically (unsigned 
+    char values). The array length is known with (width * height
+     * depth). The buffer represent image 's pixels RGBA.     
+    :param target   : Target buffer must have same length than source buffer)
+    :param width    : integer; Source array's width (image width)
+    :param height   : integer; source array's height (image height)
+    :return         : Return a vertically flipped 1D RGBA buffer 
+    (swapped rows and columns of the 2d model) 
+    """
+    return numpy.asarray(vfb_rgba_c(source, target, width, height))
+
+```
+
+``` cython
+#  FLIP VERTICALLY A BUFFER (TYPE ALPHA, (WIDTH, HEIGHT))
+cpdef unsigned char [::1] vfb(unsigned char [:] source, unsigned char [::1] target, int width,
+    int height):
+    
+    use_pygments=false
+    """
+    Flip vertically the content (e.g alpha values) of an 1d buffer
+    structure. buffer representing an array type (w, h) 
+
+    :param source : 1d buffer created from array type(w, h) 
+    :param target : 1d buffer numpy.empty(ax_ * ay_, dtype=numpy.uint8) 
+    that will be the equivalentof the source array but flipped vertically 
+    :param width  : source width. 
+    :param height : source height. 
+    :return       : return 1d buffer (source array flipped)
+    """
+    return vfb_c(source, target, width, height)
+```   
+
+``` python
+EXAMPLE :
+
+import IndexMapping
+from IndexMapping.mapping import to1d
+import pygame
+import numpy
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+w, h = background.get_size()
+rgb_array = pygame.surfarray.pixels3d(background)
+c_buffer = numpy.empty(w * h * 3, dtype=numpy.uint8)
+
+# Convert 3d array (rgb_array) into a C buffer (1d)
+for i in range(w):
+    for j in range(h):
+        for k in range(3):
+            index = to1d(i, j, k, w, 3)
+            c_buffer[index] = rgb_array[i, j, k]       
+```
+
+```python
+
+import IndexMapping
+from IndexMapping.mapping import to3d
+import pygame
+from pygame.surfarray import pixels3d
+import numpy
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+w, h = background.get_size()
+
+rgb_array = pixels3d(background).transpose(1, 0, 2)
+c_buffer = rgb_array.flatten()
+
+length = c_buffer.size
+assert length == w * h * 3, \
+    "C buffer has an incorrect length, got %s instead of %s " \ 
+% (length, w * h * 3)
+
+rgb_array = numpy.zeros((w, h, 3), numpy.uint8)
+        
+# Build a 3d array using the function to3d
+for i in range(length):
+    x, y, z = to3d(i, w, 3)
+    rgb_array[x, y, z] = c_buffer[i]
+```
+```python
+import IndexMapping
+import numpy
+from IndexMapping.mapping import vfb_rgb
+import pygame
+from pygame.surfarray import pixels3d
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+background = pygame.transform.smoothscale(background, (640, 480))
+w, h = background.get_size()
+rgb_array = pixels3d(background)
+
+rgb_buffer = rgb_array.flatten()
+target_buffer = numpy.empty(w * h * 3, numpy.uint8)
+rgb_buffer_transpose = vfb_rgb(rgb_buffer, target_buffer, w, h)
+```
+
+## Building cython code
+```
+If you need to compile the Cython code after any changes in the 
+file Mapping.pyx:
+
+1) open a terminal window
+2) Go in the main project directory where (mapping.pyx & 
+   mapping.pxd files are located)
+3) run : python setup_Mapping.py build_ext --inplace
+
+If you have to compile the code with a specific python 
+version, make sure to reference the right python version 
+in (python38 setup_mapping.py build_ext --inplace)
+
+If the compilation fail, refers to the requirement section and 
+make sure cython and a C-compiler are correctly install on your
+ system.
+- A compiler such visual studio, MSVC, CGYWIN setup correctly on 
+  your system.
+  - a C compiler for windows (Visual Studio, MinGW etc) install 
+  on your system and linked to your windows environment.
+  Note that some adjustment might be needed once a compiler is 
+  install on your system, refer to external documentation or 
+  tutorial in order to setup this process.e.g https://devblogs.
+  microsoft.com/python/unable-to-find-vcvarsall-bat/
+```
+
+## Credit
+Yoann Berenguer 
+
+## Dependencies :
+```
+python >= 3.0
+cython >= 0.28
+```
+
+## License :
+```
+MIT License
+
+Copyright (c) 2019 Yoann Berenguer
+
+Permission is hereby granted, free of charge, to any person 
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without 
+restriction, including without limitation the rights to use, 
+copy, modify, merge, publish, distribute, sublicense, and/or 
+sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following 
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+```
+## Testing: 
+```python
+>>>from IndexMapping.test.test_mapping import run_test
+>>>run_test()
+```
+
+
+## Timing :
+```C:\>python profiling.py```
+
+```
+Testing to1d        per call 2.627551e-07 overall time 0.2627551 for 1000000
+Testing to3d        per call 1.217256e-07 overall time 0.1217255 for 1000000
+Testing vfb_rgb     per call 0.0015129453 overall time 1.5129453 for 1000 --> image 800x800x3
+Testing vmap_buffer per call 1.189032e-07 overall time 0.1189032 for 1000000
+Testing vfb_rgba    per call 0.001878 overall time 1.8783595 for 1000     --> image 800x800x4
+```
+
+
+
+%package help
+Summary:	Development documents and examples for IndexMapping
+Provides:	python3-IndexMapping-doc
+%description help
+# IndexMapping 
+
+This library contains tools that helps indexing arrays from 
+`1d array` (C buffer data type) to 3d array and reciprocally.
+The functions `to1d` and `to3d` are complementary and can be
+resume with the following statment :
+```
+If we know the index value of a buffer (index), find the 
+equivalent position in a 3d array (x, y, z) and reciprocally; 
+such as :
+```
+
+- `to3d` buffer[index]     --> 3d array[x, y, z]
+- `to1d` 3d array[x, y, z] --> buffer[index]
+
+`to1d & to3d` can also be used to convert 1d array -> 3d array
+and vice versa. The library also includes functions to transpose
+C buffer data type like the numpy transpose function used for 
+multi-dimensional arrays.
+
+How can we transpose row and columns in a 1d array since 
+a buffer is a contiguous or non-contiguous adjacent set of data?
+
+1) reshape the 1d array to a 3d equivalent format 
+2) swap row and column of the equivalent 3d array (transposed) 
+3) Convert the 3d array back to 1d array type (flatten)
+
+This library provide functions such as` vfb_rgb` & `vfb_rgba` 
+(for transparency) to transpose the array directly.
+
+```
+Below a good example with 9 pixels buffer:
+// Original 9 pixels buffer (length = 27), pixel format RGB 
+(contiguous values)
+buffer = [RGB1, RGB2, *RGB3, RGB4, RGB5, RGB6, RGB7, RGB8, 
+RGB9]
+
+Equivalent reshape model (w, h, depth) would be (3x3x3):
+3d model = [RGB1 RGB2 *RGB3*]
+           [RGB4 RGB5  RGB6 ]
+           [RGB7 RGB8  RGB9 ]
+
+// Same 1d buffer after transposing the values (swapped 
+row and column)
+buffer = [RGB1, RGB4, *RGB7*, RGB2, RGB5, RGB8, RGB3, RGB6, 
+RGB9]
+
+Equivalent reshape model (w, h, depth) after transposing the
+original buffer
+3D model = [RGB1, RGB4, RGB7]
+           [RGB2, RGB5, RGB8]
+           [RGB3, RGB6, RGB9]
+```
+After transposing the buffer we can observed that the 3d 
+equivalent model is an array with `row & columns swapped`. 
+This operation would be identical to a numpy transpose 
+function such as : 3darray `transpose(1, 0, 2)`
+
+
+
+
+## Installation 
+```
+pip install Mapping
+```
+
+## Methods
+```` cython
+# MAP BUFFER INDEX VALUE INTO 3D INDEXING
+cpdef tuple to3d(unsigned int index, unsigned int width, unsigned short int depth):
+   
+    use_pygments=false
+    """
+    Index mapping (buffer indexing --> 3d array)
+    
+    :param index : python int; buffer index    
+    :param width : python int; width (3d array columns number) 
+    :param depth : python int; depth (RGB = 3) | (RGBA = 4) 
+    :return      : Return a python tuple containing x, y, z index values 
+    """
+    
+    cdef xyz v = to3d_c(index, width, depth)
+    return v.x, v.y, v.z
+````
+
+
+``` cython
+# MAP 3D INDEX VALUE INTO BUFFER INDEXING
+cpdef unsigned int to1d(unsigned int x, unsigned int y, unsigned int z, unsigned int width, unsigned short int depth):
+    
+    use_pygments=false
+    """
+    Index mapping (3d array indexing --> buffer)
+    
+    :param x     : python int; index x of the array 
+    :param y     : python int; index y of the array 
+    :param z     : python int; index z of the array 
+    :param width : python int; width of the 3d array (number of columns)
+    :param depth : python int; depth, either RGB (depth = 3) or RGBA (depth = 4)
+    :return      : python int; return the index value (1d array)
+     corresponding to a 3d array with index position  (x, y, z) 
+    """
+    return to1d_c(x, y, z, width, depth)
+```
+``` cython
+# VERTICALLY FLIP A SINGLE BUFFER VALUE
+cpdef vmap_buffer(unsigned int index, unsigned int width, unsigned int height, unsigned short int depth):
+                  
+    use_pygments=false
+    """
+    Vertically flipped a single buffer value.
+
+    Flip a C-buffer value vertically
+    Re-sample a buffer value in order to swap rows and columns of
+    its equivalent 3d model
+
+    :param index  : integer; index value to convert  
+    :param width  : integer; Original image width 
+    :param height : integer; Original image height   
+    :param depth  : integer; Original image depth=3 for RGB or 4 for RGBA
+    :return       : integer value pointing to the pixel in
+     the buffer (traversed vertically). 
+    """
+    return vmap_buffer_c(index, width, height, depth)
+```
+
+``` cython
+# FLIP VERTICALLY A BUFFER (TYPE RGB)
+cpdef np.ndarray[np.uint8_t, ndim=1] vfb_rgb(unsigned char [:] source, unsigned char [:] target,
+        int width, int height):
+     
+    use_pygments=false
+    """
+    Vertically flipped buffer containing any format of RGB colors
+    
+    :param source   : 1d buffer to flip vertically (unsigned char 
+    values). The array length is known with (width * height *
+    depth). The buffer represent  image 's pixels RGB.      
+    :param target   : Target buffer must have same length than source  buffer)
+    :param width    : integer; Source array's width (image width). 
+    :param height   : integer; source array's height (image width). 
+    :return         : Return a vertically flipped 1D RGB buffer 
+    (swapped rows and columns of the 2d model) 
+    
+    """
+    return numpy.asarray(vfb_rgb_c(source, target, width, height))
+```
+``` cython
+# FLIP VERTICALLY A BUFFER (TYPE RGBA)
+cpdef np.ndarray[np.uint8_t, ndim=1] vfb_rgba(unsigned char [:] source, unsigned char [:] target,
+        int width, int height):
+        
+    use_pygments=false
+    """
+    Vertically flipped buffer containing any format of RGBA colors
+        
+    :param source   : 1d buffer to flip vertically (unsigned 
+    char values). The array length is known with (width * height
+     * depth). The buffer represent image 's pixels RGBA.     
+    :param target   : Target buffer must have same length than source buffer)
+    :param width    : integer; Source array's width (image width)
+    :param height   : integer; source array's height (image height)
+    :return         : Return a vertically flipped 1D RGBA buffer 
+    (swapped rows and columns of the 2d model) 
+    """
+    return numpy.asarray(vfb_rgba_c(source, target, width, height))
+
+```
+
+``` cython
+#  FLIP VERTICALLY A BUFFER (TYPE ALPHA, (WIDTH, HEIGHT))
+cpdef unsigned char [::1] vfb(unsigned char [:] source, unsigned char [::1] target, int width,
+    int height):
+    
+    use_pygments=false
+    """
+    Flip vertically the content (e.g alpha values) of an 1d buffer
+    structure. buffer representing an array type (w, h) 
+
+    :param source : 1d buffer created from array type(w, h) 
+    :param target : 1d buffer numpy.empty(ax_ * ay_, dtype=numpy.uint8) 
+    that will be the equivalentof the source array but flipped vertically 
+    :param width  : source width. 
+    :param height : source height. 
+    :return       : return 1d buffer (source array flipped)
+    """
+    return vfb_c(source, target, width, height)
+```   
+
+``` python
+EXAMPLE :
+
+import IndexMapping
+from IndexMapping.mapping import to1d
+import pygame
+import numpy
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+w, h = background.get_size()
+rgb_array = pygame.surfarray.pixels3d(background)
+c_buffer = numpy.empty(w * h * 3, dtype=numpy.uint8)
+
+# Convert 3d array (rgb_array) into a C buffer (1d)
+for i in range(w):
+    for j in range(h):
+        for k in range(3):
+            index = to1d(i, j, k, w, 3)
+            c_buffer[index] = rgb_array[i, j, k]       
+```
+
+```python
+
+import IndexMapping
+from IndexMapping.mapping import to3d
+import pygame
+from pygame.surfarray import pixels3d
+import numpy
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+w, h = background.get_size()
+
+rgb_array = pixels3d(background).transpose(1, 0, 2)
+c_buffer = rgb_array.flatten()
+
+length = c_buffer.size
+assert length == w * h * 3, \
+    "C buffer has an incorrect length, got %s instead of %s " \ 
+% (length, w * h * 3)
+
+rgb_array = numpy.zeros((w, h, 3), numpy.uint8)
+        
+# Build a 3d array using the function to3d
+for i in range(length):
+    x, y, z = to3d(i, w, 3)
+    rgb_array[x, y, z] = c_buffer[i]
+```
+```python
+import IndexMapping
+import numpy
+from IndexMapping.mapping import vfb_rgb
+import pygame
+from pygame.surfarray import pixels3d
+import os
+
+PROJECT_PATH = IndexMapping.__path__
+os.chdir(PROJECT_PATH[0] + "\\test")
+
+width, height = 800, 1024
+screen = pygame.display.set_mode((width, height))
+background = pygame.image.load('../Assets/A1.png').convert()
+background = pygame.transform.smoothscale(background, (640, 480))
+w, h = background.get_size()
+rgb_array = pixels3d(background)
+
+rgb_buffer = rgb_array.flatten()
+target_buffer = numpy.empty(w * h * 3, numpy.uint8)
+rgb_buffer_transpose = vfb_rgb(rgb_buffer, target_buffer, w, h)
+```
+
+## Building cython code
+```
+If you need to compile the Cython code after any changes in the 
+file Mapping.pyx:
+
+1) open a terminal window
+2) Go in the main project directory where (mapping.pyx & 
+   mapping.pxd files are located)
+3) run : python setup_Mapping.py build_ext --inplace
+
+If you have to compile the code with a specific python 
+version, make sure to reference the right python version 
+in (python38 setup_mapping.py build_ext --inplace)
+
+If the compilation fail, refers to the requirement section and 
+make sure cython and a C-compiler are correctly install on your
+ system.
+- A compiler such visual studio, MSVC, CGYWIN setup correctly on 
+  your system.
+  - a C compiler for windows (Visual Studio, MinGW etc) install 
+  on your system and linked to your windows environment.
+  Note that some adjustment might be needed once a compiler is 
+  install on your system, refer to external documentation or 
+  tutorial in order to setup this process.e.g https://devblogs.
+  microsoft.com/python/unable-to-find-vcvarsall-bat/
+```
+
+## Credit
+Yoann Berenguer 
+
+## Dependencies :
+```
+python >= 3.0
+cython >= 0.28
+```
+
+## License :
+```
+MIT License
+
+Copyright (c) 2019 Yoann Berenguer
+
+Permission is hereby granted, free of charge, to any person 
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without 
+restriction, including without limitation the rights to use, 
+copy, modify, merge, publish, distribute, sublicense, and/or 
+sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following 
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+```
+## Testing: 
+```python
+>>>from IndexMapping.test.test_mapping import run_test
+>>>run_test()
+```
+
+
+## Timing :
+```C:\>python profiling.py```
+
+```
+Testing to1d        per call 2.627551e-07 overall time 0.2627551 for 1000000
+Testing to3d        per call 1.217256e-07 overall time 0.1217255 for 1000000
+Testing vfb_rgb     per call 0.0015129453 overall time 1.5129453 for 1000 --> image 800x800x3
+Testing vmap_buffer per call 1.189032e-07 overall time 0.1189032 for 1000000
+Testing vfb_rgba    per call 0.001878 overall time 1.8783595 for 1000     --> image 800x800x4
+```
+
+
+
+%prep
+%autosetup -n IndexMapping-1.0.2
+
+%build
+%py3_build
+
+%install
+%py3_install
+install -d -m755 %{buildroot}/%{_pkgdocdir}
+if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
+if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
+if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
+if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
+pushd %{buildroot}
+if [ -d usr/lib ]; then
+	find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+if [ -d usr/lib64 ]; then
+	find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+if [ -d usr/bin ]; then
+	find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+if [ -d usr/sbin ]; then
+	find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+touch doclist.lst
+if [ -d usr/share/man ]; then
+	find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst
+fi
+popd
+mv %{buildroot}/filelist.lst .
+mv %{buildroot}/doclist.lst .
+
+%files -n python3-IndexMapping -f filelist.lst
+%dir %{python3_sitearch}/*
+
+%files help -f doclist.lst
+%{_docdir}/*
+
+%changelog
+* Mon May 15 2023 Python_Bot <Python_Bot@openeuler.org> - 1.0.2-1
+- Package Spec generated
diff --git a/sources b/sources
new file mode 100644
index 0000000..3386897
--- /dev/null
+++ b/sources
@@ -0,0 +1 @@
+12bca605a3eaefe63aaa55e46aaab633  IndexMapping-1.0.2.tar.gz