From 0f37328b3361e02246c6f461518dbbadc703ab27 Mon Sep 17 00:00:00 2001 From: CoprDistGit Date: Mon, 15 May 2023 06:42:56 +0000 Subject: automatic import of python-indexmapping --- python-indexmapping.spec | 1132 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1132 insertions(+) create mode 100644 python-indexmapping.spec (limited to 'python-indexmapping.spec') 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 - 1.0.2-1 +- Package Spec generated -- cgit v1.2.3