{ "info": { "author": "Maxime Liquet", "author_email": "maximeliquet@free.fr", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: MIT License", "Operating System :: Microsoft :: Windows", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.7", "Topic :: Scientific/Engineering :: Hydrology" ], "description": "# screen2table\n\n**screen2table** is a simple Windows GUI program that facilitates adding culvert and cross-section data in a hydraulic model when the original data is not in a file format that can be easily processed (image, PDF, CAD).\n\n

\"Tracing

\n\nThe program allows the user to trace a shape on the screen and to define its dimensions. The traced shape is processed to either generate a Distance-Level table for a cross-section or Level-Width table for a culvert.\n\nAs the program was originally developed to facilitate the development of hydraulic models with *Mike by DHI*, its input options (cross-section or culvert) and its output (table copied to clipboard, tab-separated) are tailored to this specific use case. However, the program may prove to be useful in other situations, such as when one needs to determine the area of a complex polygon saved in a PDF file and whose extent is known.\n\n## Rationale\n\nHydraulic/hydrodynamic models (1D, 2D or 1D/2D) require as input data some geometric description of a river, its in-line structures and the structures lying in the floodplain. A river geometry is usually given as a series of cross-sections (i.e. level of the ground on a line perpendicular to the flow path). The geometry of a structure like a culvert or an arch is often described by a level (or height)-width curve.\n\nModern softwares provide modellers with methods allowing to import geometric data in a breeze. This is possible only if the input data is given in the right format, which is a GIS format in most cases. Quite frequently though, the data may just be available as drawings saved in a bunch of PDF or CAD files. Modellers have then to resort to more manual, time-consuming, and tedious methods to generate the required data table for developing their model.\n\n**screen2table** aims to fill this gap by providing a fast and easy way to retrieve that geometric data.\n\n## Quick user guide\n\n

\"Mode\"

\n\nFirst, the user should select between the *culvert* or *cross-section* mode, which have the following outputs:\n\n#### *Culvert* (closed chape):\n- Area in square meter (displayed with 2 decimals by default)\n- Level-Width table in meter (copied to clipboard with 4 decimals by default, tab-separated) that starts and end with a width of zero\n- Plot of the level-width table (in a rather unusual format, as in *Mike Hydro*)\n#### *Cross-section* (open shape):\n- Length in meter (displayed with 2 decimals by default)\n- X/Z coordinates table in meter (copied to clipboard with 4 decimals by default, tab-separated)\n- Plot of the scaled cross-section\n\nThe user is then required to perform the two following steps:\n1. *Tracing*: The drawing from which the geometry should be copied is traced by ***left-clicking*** on its outline. Tracing is stopped with a ***right-click*** anywhere on the screen (that ***does not add*** a new point). The more zoomed in the drawing on the screen, the closer to the outline the clicks, and the higher the number of points, the more accurate the geometry. Because the program records screen coordinates only, ***the drawing should not be modified (panned, zoomed in/out) on the screen while tracing it.*** The traced geometry is displayed in the program for visual inspection after the right-click, new entry boxes are now available for the following step.\n\n

\"Tracing\"

\n\n2. *Scaling and processing*: The user provides the geometry extent of the drawing (its bounding box in meter) which is used by the program to scale the recorded geometry to its real dimension and process it further. Optionnaly, an angle in degree can be provided to skew the geometry before processing it. This is for instance useful to horizontally flip a line (angle of 180\u00c2\u00b0).\n\n

\"Scaling\"

\n\n## Technical note\n\nWhile generating the output for the cross-section mode is straightforward, ***some more work is done by the program when it processes culvert data***: \n1. Additional interpolated points are added to the geometry at each clicked level (vertical screen coordinates), this is required because the width needs to be calculated at each clicked point. The interpolated points are represented with red circles on the culvert plot.\n2. If two or more points were clicked on the exact same level (in practice, it means two or more clicks hit the exact same pixel row), the question arises as to which width should be attributed to this level (the smallest? the largest?). The trick used to make the width computation easier is to transform those points so that there are two and only two points at the same level within a polygon. This is done by adding/subtracting small random numbers to those points. While this may look like a numerical trick, this is actually realistic: down to a microscopic scale there are never two indentical level measures (this is continuous data).\n3. The width is calculated at each of those clicked/derived levels (there is no regular vertical discretization), be the polygon concave or convex (it cannot be self-intersecting though).\n4. Rows in the level-width table that are almost identical, defined as an absolute change in both width and level less than 0.1 mm, are considered as duplicates. Only the first one is preserved (why? because *Mike Hydro* was not very happy with too close points in the resulting level-width table).\n\n

\"Complex

\n\n# Install\n\n**screen2table** targets ***Windows only*** (the clipboard is OS specific) and is developed based on ***Python 3.7***.\n\n## Executable\n\nAn executable file can be downloaded [here](https://github.com/maximlt/screen2table/releases/tag/0.3.0). Just run the executable to launch the program.\n\n## From source\n\nThe package is available on *pip*:\n```\npip install screen2table\n```\nIt can then be launched from the command line since an entry point `screen2table` in created during the install.\n\n## Build an executable from source\n\nThe executable file was created thanks to *PyInstaller*. Building it again can be achieved by cloning this repo, installing the dependencies found in *requirements_pyinstaller.txt* and running the following command from the root directory:\n```\npyinstaller --distpath .\\dist_pyinstaller -y --clean --onefile --windowed --add-data \"screen2table/configs.cfg;screen2table\" --version-file pyinstaller/file_version_info.txt screen2table\\screen2table.py\n```\nThe above line will create a *dist* folder containing a single executable file, *screen2table.exe*, which includes *Python*, the program and its dependencies.\n\n# Configuration\n\nA configuration file (*configs.cfg*) allows the user to tweak some internal parameters (record and stop buttons, fontsize, decimal precision of the output, etc.). It is available only when the program is used as a Python package. \n\n# Dependencies\n\n**screen2table** relies on the following *Python* packages:\n- [pynput](https://pynput.readthedocs.io/en/latest/) to record the pixel coordinates of the clicks\n- [Numpy](https://www.numpy.org/) to derive the metrics and the level-width curve\n- [Matplotlib](https://matplotlib.org/) to plot the results obviously, but also to support processing complex polygons\n- [pywin32](https://github.com/mhammond/pywin32) to copy the output table to clipboard\n\nThe GUI is developed thanks to *tkinter* that is part of the standard library.\n\n# History\n\n**screen2table** was also a learning project, hence some non-pythonic pieces of code and a number of poor design decisions.\n\n# License\n\nMIT License\n\nCopyright (c) 2019 Maxime Liquet\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/maximlt/screen2table", "keywords": "", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "screen2table", "package_url": "https://pypi.org/project/screen2table/", "platform": "", "project_url": "https://pypi.org/project/screen2table/", "project_urls": { "Homepage": "https://github.com/maximlt/screen2table" }, "release_url": "https://pypi.org/project/screen2table/0.3.0.post1/", "requires_dist": [ "matplotlib (==3.1.1)", "numpy (==1.15.4)", "pywin32 (==224)", "pynput (==1.4.4)" ], "requires_python": "~=3.7", "summary": "A Windows GUI app to generate geometric data table by tracing shapes displayed on the screen.", "version": "0.3.0.post1" }, "last_serial": 5960884, "releases": { "0.3.0": [ { "comment_text": "", "digests": { "md5": "f21dad905e62f987af1774d27c88ef47", "sha256": "71d0a7219990c0f9fc5174a76cb497944240e3fb70aa6535fdadbaad0a103622" }, "downloads": -1, "filename": "screen2table-0.3.0-py3-none-any.whl", "has_sig": false, "md5_digest": "f21dad905e62f987af1774d27c88ef47", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 20213, "upload_time": "2019-10-08T07:50:07", "url": "https://files.pythonhosted.org/packages/e5/f9/2dcd0a3ed38f3fa2212a4d7f5f9148d00f71572c06c7fc05c0b0b550c266/screen2table-0.3.0-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "478cf4a26762631e6cee34c49040cdb2", "sha256": "0f9e2acafddc815473aa0b481fde0a611db4b941aadbf53d9de7f4a8e7fc2708" }, "downloads": -1, "filename": "screen2table-0.3.0.tar.gz", "has_sig": false, "md5_digest": "478cf4a26762631e6cee34c49040cdb2", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22328, "upload_time": "2019-10-08T07:50:10", "url": "https://files.pythonhosted.org/packages/19/f2/71d6ff6b1ea48fc1eee3f882165e808e778ebf08a1a9eb6813f9de88c752/screen2table-0.3.0.tar.gz" } ], "0.3.0.post1": [ { "comment_text": "", "digests": { "md5": "e38a93466b8fec8b6fbdf1dffeb24f83", "sha256": "627610cffa9f4497ee7667578942eb2cf0ce8509160374b85ab76b6892f339e7" }, "downloads": -1, "filename": "screen2table-0.3.0.post1-py3-none-any.whl", "has_sig": false, "md5_digest": "e38a93466b8fec8b6fbdf1dffeb24f83", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": "~=3.7", "size": 20356, "upload_time": "2019-10-11T15:31:15", "url": "https://files.pythonhosted.org/packages/68/2c/9df6e6ed50c57d04ae638b4b3295ba6ce75d47cbf253de744f5a991b8d46/screen2table-0.3.0.post1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "58701280322c85b30f882e9f3ce50569", "sha256": "90d71bcc6b41b554b4e95119669a1f667bb98a675b5c97a5298d0e1fe443cad1" }, "downloads": -1, "filename": "screen2table-0.3.0.post1.tar.gz", "has_sig": false, "md5_digest": "58701280322c85b30f882e9f3ce50569", "packagetype": "sdist", "python_version": "source", "requires_python": "~=3.7", "size": 22465, "upload_time": "2019-10-11T15:31:16", "url": "https://files.pythonhosted.org/packages/5c/a2/239963e7fc762b3f4aa3e5f2735bee0548d6ca3c419b614a0cc6a24bd0c5/screen2table-0.3.0.post1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "e38a93466b8fec8b6fbdf1dffeb24f83", "sha256": "627610cffa9f4497ee7667578942eb2cf0ce8509160374b85ab76b6892f339e7" }, "downloads": -1, "filename": "screen2table-0.3.0.post1-py3-none-any.whl", "has_sig": false, "md5_digest": "e38a93466b8fec8b6fbdf1dffeb24f83", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": "~=3.7", "size": 20356, "upload_time": "2019-10-11T15:31:15", "url": "https://files.pythonhosted.org/packages/68/2c/9df6e6ed50c57d04ae638b4b3295ba6ce75d47cbf253de744f5a991b8d46/screen2table-0.3.0.post1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "58701280322c85b30f882e9f3ce50569", "sha256": "90d71bcc6b41b554b4e95119669a1f667bb98a675b5c97a5298d0e1fe443cad1" }, "downloads": -1, "filename": "screen2table-0.3.0.post1.tar.gz", "has_sig": false, "md5_digest": "58701280322c85b30f882e9f3ce50569", "packagetype": "sdist", "python_version": "source", "requires_python": "~=3.7", "size": 22465, "upload_time": "2019-10-11T15:31:16", "url": "https://files.pythonhosted.org/packages/5c/a2/239963e7fc762b3f4aa3e5f2735bee0548d6ca3c419b614a0cc6a24bd0c5/screen2table-0.3.0.post1.tar.gz" } ] }