zaowr-polsl-kisiel 0.0.13

A simple Python package used by me and a friend at the university in the course 'Advanced Image, Video and Motion Analysis'

ZAOWR Package

This is a ZAOWR (Zaawansowana Analiza Obrazu, Wideo i Ruchu, eng. Advanced Image, Video, and Motion Analysis) Python package used by me and a friend at the university.

PyPI link to the package: MAIN PyPI, TEST PyPI.

Table of contents

1. Installing the package using pip

2. Removing the package using pip

3. Creating virtual environment and installing the package

4. Testing the installation

5. Automation: building and uploading with Makefile - DEV Tutorial

6. Building package - DEV Tutorial based on official DOCS

7. Sources

Installing the package using pip

1. PyPI MAIN
   
   

   python3 -m pip install --upgrade zaowr-polsl-kisiel
   



2. TestPyPI
   
   

   python3 -m pip install --index-url https://test.pypi.org/simple/ --upgrade zaowr-polsl-kisiel
   

Removing the package using pip

python3 -m pip uninstall zaowr-polsl-kisiel

Creating virtual environment and installing the package

[!NOTE]

Complete instructions on managing Python virtual environments

can be found here.

1. Create project directory and open it (directory where you will create your files and where the venv will be created)
   
   

   testDir=/home/user/test
   

   mkdir -p $testDir
   

   cd $testDir
   

   
   
2. Create venv
   
   

   python -m venv ENV_NAME
   




[!NOTE]

ENV_NAME is the name of your venv, so you can change it however you like



3. Activate the venv (while in the project directory)
   
   

   source ENV_NAME/bin/activate
   

   or

   . ENV_NAME/bin/activate
   



4. Install the package from PyPI
   
   

   python3 -m pip install --upgrade zaowr-polsl-kisiel
   



5. (ADDITIONAL COMMAND) If you want to deactivate the currently active venv
   
   

   deactivate
   



6. (ADDITIONAL COMMAND) To reactivate the venv, navigate to the path where you created the venv and source it again (command shown above in section number 3)

Testing the installation

• Activate the venv (while in the project directory) - Skip this step if you are not using a virtual environment
  
  

  source ENV_NAME/bin/activate
  

  or

  . ENV_NAME/bin/activate
  



• Launch python
  
  

  python3
  



• Import the package
  
  

  from zaowr_polsl_kisiel import load_calibration
  



• Locate the file with calibration params or create new file with structure shown below
  
  

  {
  	"mse": 5.984166144997382,
  	"rms": 0.5399844606283781,
  	"cameraMatrix": [
  		[1272.011234078766, 0.0, 1058.4537673810164],
  		[0.0, 1266.8726860857762, 617.7592332273604],
  		[0.0, 0.0, 1.0]
  	],
  	"distortionCoefficients": [
  		[-0.39935647747478337, 0.18200290247627665, 0.0020154085712910707, -0.012190829753206725, -0.04648398598417859]
  	],
  	"rotationVectors": [
  		[[0.014376302442723948], [0.1667778841470017], [0.018832348485715023]],
  		[[-0.3405035725192283], [0.526867552280327], [-0.13373157952652456]]
  	],
  	"translationVectors": [
  		[[71.27846898868391], [50.76036240921024], [1400.9402673825555]],
  		[[-476.2081267995082], [-120.35757569213392], [803.862414335442]]
  	]
  }
  



• Try reading the params from file
  
  

  # remember to provide appropriate path to the calibration params
  # you can simply create a json file with structure shown above
  calibrationParams = load_calibration("../../tests/calibration_params/calibration_params.json")
  



• Display the MSE value to test if the load succeeded
  
  

  print(calibrationParams["mse"])
  

Automation: building and uploading with Makefile - DEV Tutorial

In the project directory run make. This command will run the Makefile, which performs actions listed below:

• remove old version of the package,
• ask which version we want to update (major, minor, patch) and increment it automatically, push the changes to GitHub with new tag,
• build a new version,
• upload the package to PyPI,
• upload the package to TestPyPI.

At this moment the Makefile is configured to only delete the old release, create a new tag and push it to GitHub. The custom workflow handles building and uploading the package on new tag push.

1. Test the Makefile
   
   

   make --dry-run
   



2. Run the Makefile
   
   

   make
   

Building package - DEV Tutorial based on official DOCS

1. Install pip
   
   

   python3 -m pip install --upgrade pip
   



2. Prepare files and directories
   
   

   directory_used_for_package/
   ├── LICENSE
   ├── pyproject.toml
   ├── README.md
   ├── src/
   │   └── name_of_the_package/
   │       ├── __init__.py
   │       └── example.py
   └── tests/
   



3. Choose build backend (I chose setuptools)
   
   

   python3 -m pip install --upgrade setuptools
   



4. Prepare pyproject.toml file (this package's configuration as an example)
   
   

   [build-system]
   requires = ["setuptools>=61.0"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "zaowr_polsl_kisiel"
   dynamic = ["version", "dependencies"]
   authors = [
     { name="Maksymilian Kisiel" },
   ]
   description = "A simple Python package used by me and a friend at the university in the course 'Advanced Image, Video and Motion Analysis'"
   readme = "README.md"
   requires-python = ">=3.8"
   classifiers = [
       "Programming Language :: Python :: 3",
       "License :: OSI Approved :: MIT License",
       "Operating System :: OS Independent",
   ]
   keywords = ["polsl", "zaowr", "2024", "IGT", "ZAOWR"]
   
   [tool.setuptools.dynamic]
   version = {attr = "zaowr_polsl_kisiel.__version__"}  # any module attribute compatible with ast.literal_eval
   dependencies = {file = ["requirements.txt"]}
   
   [project.urls]
   Homepage = "https://github.com/revalew/zaowr-py-package"
   Issues = "https://github.com/revalew/zaowr-py-package/issues"
   




[!NOTE]

requirements.txt file listed as "dependencies" was created using pip freeze > requirements.txt command

which was executed in active python venv prepared for this uni course.

Check my tutorial on managing venvs here.



5. Prepare README.md file (customize this as you’d like)


6. Prepare LICENSE file (MIT license shown below, more licenses can be found here)
   
   

   Copyright (c) 2018 The Python Packaging Authority
   
   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.
   



7. Instal the build tool (if you encounter errors see official tutorial)
   
   

   python3 -m pip install --upgrade build
   



8. Navigate to the folder where the pyproject.toml file is located


9. Generate distribution archives
   
   

   python3 -m build
   



10. Verify that the build was successful
    

    In the package there should now be dist/ directory. The tar.gz file is a source distribution whereas the .whl file is a built distribution. Newer pip versions preferentially install built distributions, but will fall back to source distributions if needed. You should always upload a source distribution and provide built distributions for the platforms your project is compatible with.

    
    

    dist/
    ├── zaowr_polsl_kisiel-0.0.0-py3-none-any.whl
    └── zaowr_polsl_kisiel-0.0.0.tar.gz
    



11. Register the account in TestPyPI or PyPI (just follow the given instructions)


12. Generate API token for TestPyPI or PyPI (just follow the given instructions, I added the credentials to $HOME/.pypirc using [pypi] and [testpypi] headers)


13. Instal twine to upload the package
    
    

    python3 -m pip install --upgrade twine
    



14. Upload the package
    
    • If you didn't add the credentials to $HOME/.pypirc, you will be prompted for username and password. Use __token__ for username and pypi-* (your API token) for password
    
    
    • PyPI
      
      

      python3 -m twine upload dist/*
      

    
    
    • TestPyPI
      
      

      python3 -m twine upload --repository testpypi dist/*
      



15. After the upload succeeded, the package should be vievable on PyPI or TestPyPI


16. Installing the package
    
    • PyPI
      
      

      python3 -m pip install --upgrade zaowr-polsl-kisiel
      

    
    
    • TestPyPI
      
      

      python3 -m pip install --upgrade --index-url https://test.pypi.org/simple/ --no-deps zaowr-polsl-kisiel
      

    
    

[!NOTE]

Here we additionally use --no-deps flag.

Since TestPyPI doesn’t have the same packages as the live PyPI, it’s possible that attempting to install dependencies may fail or install something unexpected.



17. Test the installation
    
    • Activate the venv (while in the project directory) - Skip this step if you are not using a virtual environment
      
      

      source ENV_NAME/bin/activate
      

      or

      . ENV_NAME/bin/activate
      

    
    
    • Launch python
      
      

      python3
      

    
    
    • Import the package
      
      

      from zaowr_polsl_kisiel import load_calibration
      

    
    
    • Locate the file with calibration params or create new file with structure shown below
      
      

      {
      	"mse": 5.984166144997382,
      	"rms": 0.5399844606283781,
      	"cameraMatrix": [
      		[1272.011234078766, 0.0, 1058.4537673810164],
      		[0.0, 1266.8726860857762, 617.7592332273604],
      		[0.0, 0.0, 1.0]
      	],
      	"distortionCoefficients": [
      		[-0.39935647747478337, 0.18200290247627665, 0.0020154085712910707, -0.012190829753206725, -0.04648398598417859]
      	],
      	"rotationVectors": [
      		[[0.014376302442723948], [0.1667778841470017], [0.018832348485715023]],
      		[[-0.3405035725192283], [0.526867552280327], [-0.13373157952652456]]
      	],
      	"translationVectors": [
      		[[71.27846898868391], [50.76036240921024], [1400.9402673825555]],
      		[[-476.2081267995082], [-120.35757569213392], [803.862414335442]]
      	]
      }
      

    
    
    • Try reading the params from file
      
      

      # remember to provide appropriate path to the calibration params
      # you can simply create a json file with structure shown above
      calibrationParams = load_calibration("../../tests/calibration_params/calibration_params.json")
      

    
    
    • Display the MSE value to test if the load succeeded
      
      

      print(calibrationParams["mse"])
      

Sources

This package has been prepared following this tutorial.

The publishing to PyPI was created with this tutorial