| Name | qrImageIndexer JSON |
| Version |
0.7.4
JSON |
| download |
| home_page | |
| Summary | Tool for indexing images with QR codes |
| upload_time | 2023-05-23 06:40:29 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | MIT License Copyright (c) 2022 Jonathan Pecar 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. |
| keywords |
sorter
qrcode
photosorter
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# qrCodeImageSorter
## Project Outline
---
This is a python module which is designed to assist in the easy capture and sorting of photos.
It aims to solve a problem I have identified where a large number of photos need to be taken
in a structured manner. While there are apps which aim to acheive this natively on device,
these can sometimes make sharing of the task difficult. They are often also not as fast as
the native camera apps, also sometimes missing some of the native post-processing on phones.
This tool will allow users to produce a simple list of QR codes that can be used as indices
in the photos. The photos will then be split into folders based on the content of the QR
codes.
## Operational Philosophy
---
The principal of this tool is to generate QR codes which can be printed and included in the photo
set being captured. Images with QR codes included will be detected and used as index photos. Any
photos found after (and including) the index photo, up to the next index photo, will be sorted
into a directory as indicated by the QR code. Photos will be processed in file name order as
this is consistent with the capture method of all phones and cameras I have personally used.
All sorting is done through copying. The original files are left in-place and unmodified.
QR codes may appear in the images in any order. As the directory is determined by the QR code,
it will be sorted accordingly. The same code may also appear multiple times and will simply add
the additional content to the resulting directory.
### Sorting Exceptions
---
#### Non-Images
As the tool is targetting images, any files which are not images will be copied into the
directory `non_image_files/` under the target output directory.
#### Files Before Index Image
If there are images which appear before the first QR-containing image will be copied into
the directory `unsorted/`.
### Example Input Images
## Installation
---
The package is available on PyPi and can be installed with the following command:
```pip install qrImageIndexer```
If you are not using Windows you will also need to install the zBar binaries (these are included
in the wheel for Windows users): https://pypi.org/project/pyzbar/
## Instructions
---
### Tool Command Line Arguments
---
To use the tool run the command:
```python -m qrImageIndexer```
Command line useage is as per below:
```
usage: qrImageIndexer [-h] [-g INPUT_TEXT_FILE OUTPUT_PDF | -s INPUT_DIR OUTPUT_DIR] [--pdf-type SORT_TYPE] [-q] [-r] [-p STRING_PREFIX] [-v]
options:
-h, --help show this help message and exit
-g INPUT_TEXT_FILE OUTPUT_PDF, --generate-pdf INPUT_TEXT_FILE OUTPUT_PDF
Generate a PDF of QR codes from a given text file. Specify
-s INPUT_DIR OUTPUT_DIR, --sort-photos INPUT_DIR OUTPUT_DIR
Sort photos based on QR codes found in photos. Once a QR code is found all photos will be sorted into the directory indicated by the code until subsequent codes found
--pdf-type SORT_TYPE Type of PDF to generate. Either linearly sorted or sorted to enable easy slicing of the printed pages. Accepts "linear" or "sliceable". Linear will sort down page, sliceable will sort "through" the page.
-q, --qr-for-headings
Generate a QR code for each heading, not just a code for the last items in a tree.
-r, --repeat-table-headings
Repeat table headings on every line
-p STRING_PREFIX, --string-prefix STRING_PREFIX
Specify a prefix for use in the generated QR codes to differentiate from codes that might also end up in photos
-v, --verbose Turn progress text to terminal on or off
```
### General usage
---
In general usage the user will generate QR codes from a text file. These QR codes will then be used as index cards while taking photos. Any photos
which appear subsequent to a QR code but before the next QR code will be sorted into a folder. Any photos which appear before a QR code will be sorted
into a specific folder of their own.
#### PDF Format
---
For ease of use it is recommended to use the `--pdf-type sliceable` option, which will allow, when printed single-sided, for the QR codes to be easily sliced
and stacked for use in-order.
#### File Format
---
Expected input file format is as a tab indented list. Each level of indentation is considered a child tested below the preceeding level. When photos are sorted
these nested elements will form the file paths. **Additional file formats could easily be added
and may be a good first issue for anyone who wishes to contribute.** An example input file is shown below:
```
Line 1
Line 1 1st indent item 1
Line 1 2nd indent
Line 1 1st indent item 2
Line 2
Line 3
Line 4
Line 5
Line 6
```
In this case photos under `Line 1 1st indent item 1` would appear in the directory `Line 1/Line 1 1st indent item 1/` and photos under `Line 1 2nd
indent` will appear in the directory `Line 1/Line 1 1st indent item 1/Line 1 2nd indent/`.
Generally it is recommended that folder structure be used to sort and plan photo capture logically. E.g. level 1 of the
structure may be particular rooms, level 2 may be objects in the room and level 3 may be specifics about the object.
There is no limit on the number of levels that may be included in the document, but higher numbers will result in messier/busier output PDFs.
#### Other Recommended Options
---
Other options such as `-r` which will result in the headings from further up the tree being repeaded in the output PDF and `-q` which will generate QR codes for headings as well as the tails of the tree may both also be useful.
If it is expected that other QR codes may be present, a prefix can also be added to the QR code package. This can be done with the `-p` option.
Using the option `-v` for any operations will provide verbose status output to the command line.
#### Generating PDF Document
---
Assuming that the above demo file is saved as `demo.txt` the following command would generate a PDF with repeated headings and qr codes for each line in a sliceable format, with the prefix `{image}`:
```python -m qrImageIndexer -g demo.txt demo.pdf -r -q --pdf-type sliceable -p "{image}"```
#### Sorting Images
---
After taking photos, these images could then be sorted into a folder called `outputs\` from a folder called `inputs\` as shown below:
```python -m qrImageIndexer -s inputs\ outputs\ -p "{image}"```
## Future Features
---
Currently the module is command line only. In future this will be expanded to include a GUI
which will simplify the generation of QR codes and the scanning of images for users.
Raw data
{
"_id": null,
"home_page": "",
"name": "qrImageIndexer",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "sorter,qrcode,photosorter",
"author": "",
"author_email": "Jonathan Pecar <jonathan.pecar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a1/8e/8460e0a678855b75c86f74f433b7dc24b8d151412aaee2b7a930e1142a67/qrImageIndexer-0.7.4.tar.gz",
"platform": null,
"description": "# qrCodeImageSorter\n\n## Project Outline\n---\n\nThis is a python module which is designed to assist in the easy capture and sorting of photos. \nIt aims to solve a problem I have identified where a large number of photos need to be taken \nin a structured manner. While there are apps which aim to acheive this natively on device, \nthese can sometimes make sharing of the task difficult. They are often also not as fast as \nthe native camera apps, also sometimes missing some of the native post-processing on phones.\n\nThis tool will allow users to produce a simple list of QR codes that can be used as indices \nin the photos. The photos will then be split into folders based on the content of the QR \ncodes.\n\n## Operational Philosophy\n---\n\nThe principal of this tool is to generate QR codes which can be printed and included in the photo\nset being captured. Images with QR codes included will be detected and used as index photos. Any\nphotos found after (and including) the index photo, up to the next index photo, will be sorted \ninto a directory as indicated by the QR code. Photos will be processed in file name order as\nthis is consistent with the capture method of all phones and cameras I have personally used.\n\nAll sorting is done through copying. The original files are left in-place and unmodified.\n\nQR codes may appear in the images in any order. As the directory is determined by the QR code,\nit will be sorted accordingly. The same code may also appear multiple times and will simply add\nthe additional content to the resulting directory.\n\n### Sorting Exceptions\n---\n#### Non-Images\nAs the tool is targetting images, any files which are not images will be copied into the\ndirectory `non_image_files/` under the target output directory.\n#### Files Before Index Image\nIf there are images which appear before the first QR-containing image will be copied into\nthe directory `unsorted/`.\n\n### Example Input Images\n\n\n## Installation\n---\n\nThe package is available on PyPi and can be installed with the following command:\n\n```pip install qrImageIndexer```\n\nIf you are not using Windows you will also need to install the zBar binaries (these are included\nin the wheel for Windows users): https://pypi.org/project/pyzbar/\n\n## Instructions\n---\n\n### Tool Command Line Arguments\n---\n\nTo use the tool run the command:\n\n```python -m qrImageIndexer```\n\nCommand line useage is as per below:\n```\nusage: qrImageIndexer [-h] [-g INPUT_TEXT_FILE OUTPUT_PDF | -s INPUT_DIR OUTPUT_DIR] [--pdf-type SORT_TYPE] [-q] [-r] [-p STRING_PREFIX] [-v]\n\noptions:\n -h, --help show this help message and exit\n -g INPUT_TEXT_FILE OUTPUT_PDF, --generate-pdf INPUT_TEXT_FILE OUTPUT_PDF\n Generate a PDF of QR codes from a given text file. Specify\n -s INPUT_DIR OUTPUT_DIR, --sort-photos INPUT_DIR OUTPUT_DIR\n Sort photos based on QR codes found in photos. Once a QR code is found all photos will be sorted into the directory indicated by the code until subsequent codes found\n --pdf-type SORT_TYPE Type of PDF to generate. Either linearly sorted or sorted to enable easy slicing of the printed pages. Accepts \"linear\" or \"sliceable\". Linear will sort down page, sliceable will sort \"through\" the page.\n -q, --qr-for-headings\n Generate a QR code for each heading, not just a code for the last items in a tree.\n -r, --repeat-table-headings\n Repeat table headings on every line\n -p STRING_PREFIX, --string-prefix STRING_PREFIX\n Specify a prefix for use in the generated QR codes to differentiate from codes that might also end up in photos\n -v, --verbose Turn progress text to terminal on or off\n```\n\n### General usage\n---\n\nIn general usage the user will generate QR codes from a text file. These QR codes will then be used as index cards while taking photos. Any photos\nwhich appear subsequent to a QR code but before the next QR code will be sorted into a folder. Any photos which appear before a QR code will be sorted\n into a specific folder of their own.\n\n#### PDF Format\n---\n\nFor ease of use it is recommended to use the `--pdf-type sliceable` option, which will allow, when printed single-sided, for the QR codes to be easily sliced\nand stacked for use in-order.\n\n\n\n#### File Format\n---\n\nExpected input file format is as a tab indented list. Each level of indentation is considered a child tested below the preceeding level. When photos are sorted\nthese nested elements will form the file paths. **Additional file formats could easily be added\nand may be a good first issue for anyone who wishes to contribute.** An example input file is shown below:\n\n```\nLine 1\n Line 1 1st indent item 1\n Line 1 2nd indent\n Line 1 1st indent item 2\nLine 2\nLine 3\nLine 4\nLine 5\nLine 6\n```\n\nIn this case photos under `Line 1 1st indent item 1` would appear in the directory `Line 1/Line 1 1st indent item 1/` and photos under `Line 1 2nd\nindent` will appear in the directory `Line 1/Line 1 1st indent item 1/Line 1 2nd indent/`.\n\nGenerally it is recommended that folder structure be used to sort and plan photo capture logically. E.g. level 1 of the\nstructure may be particular rooms, level 2 may be objects in the room and level 3 may be specifics about the object.\n\nThere is no limit on the number of levels that may be included in the document, but higher numbers will result in messier/busier output PDFs.\n\n#### Other Recommended Options\n---\n\nOther options such as `-r` which will result in the headings from further up the tree being repeaded in the output PDF and `-q` which will generate QR codes for headings as well as the tails of the tree may both also be useful.\n\nIf it is expected that other QR codes may be present, a prefix can also be added to the QR code package. This can be done with the `-p` option.\n\nUsing the option `-v` for any operations will provide verbose status output to the command line.\n\n#### Generating PDF Document\n---\n\nAssuming that the above demo file is saved as `demo.txt` the following command would generate a PDF with repeated headings and qr codes for each line in a sliceable format, with the prefix `{image}`:\n\n```python -m qrImageIndexer -g demo.txt demo.pdf -r -q --pdf-type sliceable -p \"{image}\"```\n\n#### Sorting Images\n---\n\nAfter taking photos, these images could then be sorted into a folder called `outputs\\` from a folder called `inputs\\` as shown below:\n\n```python -m qrImageIndexer -s inputs\\ outputs\\ -p \"{image}\"```\n\n## Future Features\n---\n\nCurrently the module is command line only. In future this will be expanded to include a GUI\nwhich will simplify the generation of QR codes and the scanning of images for users.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 Jonathan Pecar 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. ",
"summary": "Tool for indexing images with QR codes",
"version": "0.7.4",
"project_urls": {
"Homepage": "https://github.com/jonpecar/qrCodeImageSorter"
},
"split_keywords": [
"sorter",
"qrcode",
"photosorter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c3f3499b97ed17922e1f05c0627125d96f57a3c8c36f2965f3b9d3a63f595bb",
"md5": "bf06b11e3ea107f18937b1a7da11cdae",
"sha256": "dd8ef8579663790b479083caf8aac880c0b32036c8113e816733156ece4604d4"
},
"downloads": -1,
"filename": "qrImageIndexer-0.7.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf06b11e3ea107f18937b1a7da11cdae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 15587,
"upload_time": "2023-05-23T06:40:28",
"upload_time_iso_8601": "2023-05-23T06:40:28.224960Z",
"url": "https://files.pythonhosted.org/packages/4c/3f/3499b97ed17922e1f05c0627125d96f57a3c8c36f2965f3b9d3a63f595bb/qrImageIndexer-0.7.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a18e8460e0a678855b75c86f74f433b7dc24b8d151412aaee2b7a930e1142a67",
"md5": "baca05ae5cae89a86091d0cdd4df3e4e",
"sha256": "06219fb4805b0cc21ee5e5f31ff045202863c1d3368789e91043fd7e1f48973e"
},
"downloads": -1,
"filename": "qrImageIndexer-0.7.4.tar.gz",
"has_sig": false,
"md5_digest": "baca05ae5cae89a86091d0cdd4df3e4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 20348,
"upload_time": "2023-05-23T06:40:29",
"upload_time_iso_8601": "2023-05-23T06:40:29.715269Z",
"url": "https://files.pythonhosted.org/packages/a1/8e/8460e0a678855b75c86f74f433b7dc24b8d151412aaee2b7a930e1142a67/qrImageIndexer-0.7.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-23 06:40:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jonpecar",
"github_project": "qrCodeImageSorter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "qrimageindexer"
}
