endocal


Nameendocal JSON
Version 18.2.13 PyPI version JSON
download
home_pagehttps://github.com/gift-surg/endocal
SummaryA cross-platform, compact GUI application for the optical distortion calibration of fluid-immersed endoscopes.
upload_time2018-02-13 20:00:22
maintainer
docs_urlNone
authorDzhoshkun Ismail Shakir
requires_python
licenseBSD-3-Clause
keywords optical distortion calibration endoscope endoscopy medical imaging image processing biomedical engineering medical physics image-guided interventions
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            endocal is a cross-platform, compact GUI application for the optical distortion calibration of fluid-immersed
endoscopes. It uses the `OpenCV`_ camera calibration module.

endocal was developed by Dzhoshkun I. Shakir as part of the `GIFT-Surg project`_ at the
`Translational Imaging Group`_ in the `Centre for Medical Image Computing`_ at
`University College London (UCL)`_.

.. _`GIFT-Surg project`: http://www.gift-surg.ac.uk
.. _`Translational Imaging Group`: http://cmictig.cs.ucl.ac.uk
.. _`Centre for Medical Image Computing`: http://cmic.cs.ucl.ac.uk
.. _`University College London (UCL)`: http://www.ucl.ac.uk

Features
--------

* Lightweight, compact GUI application for optical distortion calibration of endoscopes
* Command-line application for generating `ASCII DXF files`_ for use in calibration target fabrication (translated\
  from Matlab scripts developed by Daniil I. Nikitichev)

The detailed changelog is available on `GitHub`_.

.. _`ASCII DXF files`: http://www.autodesk.com/techpubs/autocad/acadr14/dxf/
.. _`GitHub`: https://github.com/gift-surg/endocal/blob/master/CHANGELOG.md

System requirements
-------------------

* `Python`_
* `pip`_
* `OpenCV`_ (installed with `Python`_ support)
* For live calibration: a video source `supported by OpenCV`_ (see esp. the OpenCV tutorials related
  to video IO)
* `PyYAML`_
* `NumPy`_
* So far endocal has been tested on the following operating systems:

  - Ubuntu 16.04.3 LTS 64-bit
  - Ubuntu 14.04.3 LTS 64-bit
  - elementary OS Freya 0.3.2 64-bit
  - macOS Sierra 10.12.6
  - OS X El Capitan 10.11.3
  - Windows 10 Professional 64-bit

.. _`Python`: https://www.python.org/
.. _`pip`: https://pip.pypa.io/en/stable/installing/
.. _`supported by OpenCV`: http://docs.opencv.org/
.. _`PyYAML`: https://github.com/yaml/pyyaml
.. _`NumPy`: http://www.numpy.org/
.. _`OpenCV`: http://opencv.org/

Installation
------------

Installing endocal
^^^^^^^^^^^^^^^^^^

``pip install endocal``

Testing your installation
^^^^^^^^^^^^^^^^^^^^^^^^^

* Launch the test application by running ``endocal-test``.
* `This screenshot`_ shows you what to expect on launching the application.
* To perform an optical distortion calibration, follow the instructions shown in red on top of the application window.
* While acquiring calibration data, detected calibration pattern blobs will be emphasized with a virtual overlay as
  in `this acquisition-mode screenshot`_.
* All data for each calibration will be saved in a human-readably time-stamped, uniquely-named folder within a root 
  folder named ``tmp-sample_002`` created within the folder where the application was launched.
  For instance ``tmp-sample_002/2018-02-08-11-03-19-AHDHO`` for a calibration run on 8 February 2018 at 11:03 am.
  The saved data includes:

  * A `YAML`_ file named ``calibration.yml`` with the computed calibration parameters
  * Frames used for calibration saved as indexed image files, e.g. ``frame_009.jpg``

* After performing a calibration, the application will automatically show the undistorted images in real time to the
  right of the application window as in `this undistortion-mode screenshot`_.

.. _`This screenshot`: https://github.com/gift-surg/endocal/blob/master/endocal/res/screenshot-start.png
.. _`this acquisition-mode screenshot`: https://github.com/gift-surg/endocal/blob/master/endocal/res/screenshot-detection.png
.. _`YAML`: http://yaml.org/
.. _`this undistortion-mode screenshot`: https://github.com/gift-surg/endocal/blob/master/endocal/res/screenshot-undistort.png

Uninstalling endocal
^^^^^^^^^^^^^^^^^^^^

``pip uninstall endocal``

Usage
-----

Calibration
^^^^^^^^^^^

``endocal --help`` shows details of what input parameters are expected. Some examples are provided below:

* Offline calibration by using all frames saved as indexed image files in a ``/data/offline`` folder:

.. code-block:: sh

  endocal --pattern-specs 3 11 3 1 --output-folder ./calibration-results --input /data/offline/frame_%03d.jpg

* Live calibration using a real-time video stream from an endoscope provided by a frame-grabber (assuming the 
  frame-grabber is `mounted`_ as ``/dev/video0``):

.. code-block:: sh

  endocal --input 0 --pattern-specs 3 11 3 1 --output-folder ./calibration-results

.. _`mounted`: https://help.ubuntu.com/community/Webcam

* Using a ``700 x 700`` sub-frame of the whole endoscopic video frame (whose full size is e.g. ``1920 x 1080``):

.. code-block:: sh

  endocal --input 0 --pattern-specs 3 11 3 1 --output-folder ./calibration-results --roi 620 200 700 700

ASCII DXF file generation
^^^^^^^^^^^^^^^^^^^^^^^^^

``dxf --help`` shows details of what input parameters are expected.

For instance to generate an asymmetric grid of circles each with a diameter of ``1 mm`` to be etched by a laser
cutter with a beam width of ``45 μm`` (microns):

.. code-block:: sh

  dxf --laser-beam-width 45 --diameter 1 --output-file output.dxf

Here the grid is saved to file ``output.dxf`` and the corresponding (ellipse) legend to ``output-legend.dxf`` (legend
filename always inferred from main DXF filename).

Troubleshooting
^^^^^^^^^^^^^^^

Please check out `these hints`_ in case you encounter any issues with endocal.

.. _`these hints`: https://github.com/gift-surg/endocal/blob/master/doc/issues.md

Licensing and copyright
-----------------------

Copyright (c) 2016, `University College London`_. endocal is available as free open-source software under a
BSD 3-Clause Licence.

.. _`University College London`: http://www.ucl.ac.uk

Acknowledgements
----------------

This work was supported through an Innovative Engineering for Health award by the `Wellcome Trust`_
[WT101957], the `Engineering and Physical Sciences Research Council (EPSRC)`_ [NS/A000027/1] and a
`National Institute for Health Research`_ Biomedical Research Centre `UCLH`_/UCL High Impact Initiative.


.. _`National Institute for Health Research`: http://www.nihr.ac.uk
.. _`UCLH`: http://www.uclh.nhs.uk
.. _`Engineering and Physical Sciences Research Council (EPSRC)`: http://www.epsrc.ac.uk
.. _`Wellcome Trust`: http://www.wellcome.ac.uk



            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "optical distortion calibration,endoscope,endoscopy,medical imaging,image processing,biomedical engineering,medical physics,image-guided interventions", 
    "upload_time": "2018-02-13 20:00:22", 
    "author": "Dzhoshkun Ismail Shakir", 
    "home_page": "https://github.com/gift-surg/endocal", 
    "github_user": "gift-surg", 
    "download_url": "", 
    "platform": "", 
    "version": "18.2.13", 
    "cheesecake_documentation_id": null, 
    "description": "endocal is a cross-platform, compact GUI application for the optical distortion calibration of fluid-immersed\nendoscopes. It uses the `OpenCV`_ camera calibration module.\n\nendocal was developed by Dzhoshkun I. Shakir as part of the `GIFT-Surg project`_ at the\n`Translational Imaging Group`_ in the `Centre for Medical Image Computing`_ at\n`University College London (UCL)`_.\n\n.. _`GIFT-Surg project`: http://www.gift-surg.ac.uk\n.. _`Translational Imaging Group`: http://cmictig.cs.ucl.ac.uk\n.. _`Centre for Medical Image Computing`: http://cmic.cs.ucl.ac.uk\n.. _`University College London (UCL)`: http://www.ucl.ac.uk\n\nFeatures\n--------\n\n* Lightweight, compact GUI application for optical distortion calibration of endoscopes\n* Command-line application for generating `ASCII DXF files`_ for use in calibration target fabrication (translated\\\n  from Matlab scripts developed by Daniil I. Nikitichev)\n\nThe detailed changelog is available on `GitHub`_.\n\n.. _`ASCII DXF files`: http://www.autodesk.com/techpubs/autocad/acadr14/dxf/\n.. _`GitHub`: https://github.com/gift-surg/endocal/blob/master/CHANGELOG.md\n\nSystem requirements\n-------------------\n\n* `Python`_\n* `pip`_\n* `OpenCV`_ (installed with `Python`_ support)\n* For live calibration: a video source `supported by OpenCV`_ (see esp. the OpenCV tutorials related\n  to video IO)\n* `PyYAML`_\n* `NumPy`_\n* So far endocal has been tested on the following operating systems:\n\n  - Ubuntu 16.04.3 LTS 64-bit\n  - Ubuntu 14.04.3 LTS 64-bit\n  - elementary OS Freya 0.3.2 64-bit\n  - macOS Sierra 10.12.6\n  - OS X El Capitan 10.11.3\n  - Windows 10 Professional 64-bit\n\n.. _`Python`: https://www.python.org/\n.. _`pip`: https://pip.pypa.io/en/stable/installing/\n.. _`supported by OpenCV`: http://docs.opencv.org/\n.. _`PyYAML`: https://github.com/yaml/pyyaml\n.. _`NumPy`: http://www.numpy.org/\n.. _`OpenCV`: http://opencv.org/\n\nInstallation\n------------\n\nInstalling endocal\n^^^^^^^^^^^^^^^^^^\n\n``pip install endocal``\n\nTesting your installation\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n* Launch the test application by running ``endocal-test``.\n* `This screenshot`_ shows you what to expect on launching the application.\n* To perform an optical distortion calibration, follow the instructions shown in red on top of the application window.\n* While acquiring calibration data, detected calibration pattern blobs will be emphasized with a virtual overlay as\n  in `this acquisition-mode screenshot`_.\n* All data for each calibration will be saved in a human-readably time-stamped, uniquely-named folder within a root \n  folder named ``tmp-sample_002`` created within the folder where the application was launched.\n  For instance ``tmp-sample_002/2018-02-08-11-03-19-AHDHO`` for a calibration run on 8 February 2018 at 11:03 am.\n  The saved data includes:\n\n  * A `YAML`_ file named ``calibration.yml`` with the computed calibration parameters\n  * Frames used for calibration saved as indexed image files, e.g. ``frame_009.jpg``\n\n* After performing a calibration, the application will automatically show the undistorted images in real time to the\n  right of the application window as in `this undistortion-mode screenshot`_.\n\n.. _`This screenshot`: https://github.com/gift-surg/endocal/blob/master/endocal/res/screenshot-start.png\n.. _`this acquisition-mode screenshot`: https://github.com/gift-surg/endocal/blob/master/endocal/res/screenshot-detection.png\n.. _`YAML`: http://yaml.org/\n.. _`this undistortion-mode screenshot`: https://github.com/gift-surg/endocal/blob/master/endocal/res/screenshot-undistort.png\n\nUninstalling endocal\n^^^^^^^^^^^^^^^^^^^^\n\n``pip uninstall endocal``\n\nUsage\n-----\n\nCalibration\n^^^^^^^^^^^\n\n``endocal --help`` shows details of what input parameters are expected. Some examples are provided below:\n\n* Offline calibration by using all frames saved as indexed image files in a ``/data/offline`` folder:\n\n.. code-block:: sh\n\n  endocal --pattern-specs 3 11 3 1 --output-folder ./calibration-results --input /data/offline/frame_%03d.jpg\n\n* Live calibration using a real-time video stream from an endoscope provided by a frame-grabber (assuming the \n  frame-grabber is `mounted`_ as ``/dev/video0``):\n\n.. code-block:: sh\n\n  endocal --input 0 --pattern-specs 3 11 3 1 --output-folder ./calibration-results\n\n.. _`mounted`: https://help.ubuntu.com/community/Webcam\n\n* Using a ``700 x 700`` sub-frame of the whole endoscopic video frame (whose full size is e.g. ``1920 x 1080``):\n\n.. code-block:: sh\n\n  endocal --input 0 --pattern-specs 3 11 3 1 --output-folder ./calibration-results --roi 620 200 700 700\n\nASCII DXF file generation\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n``dxf --help`` shows details of what input parameters are expected.\n\nFor instance to generate an asymmetric grid of circles each with a diameter of ``1 mm`` to be etched by a laser\ncutter with a beam width of ``45 \u03bcm`` (microns):\n\n.. code-block:: sh\n\n  dxf --laser-beam-width 45 --diameter 1 --output-file output.dxf\n\nHere the grid is saved to file ``output.dxf`` and the corresponding (ellipse) legend to ``output-legend.dxf`` (legend\nfilename always inferred from main DXF filename).\n\nTroubleshooting\n^^^^^^^^^^^^^^^\n\nPlease check out `these hints`_ in case you encounter any issues with endocal.\n\n.. _`these hints`: https://github.com/gift-surg/endocal/blob/master/doc/issues.md\n\nLicensing and copyright\n-----------------------\n\nCopyright (c) 2016, `University College London`_. endocal is available as free open-source software under a\nBSD 3-Clause Licence.\n\n.. _`University College London`: http://www.ucl.ac.uk\n\nAcknowledgements\n----------------\n\nThis work was supported through an Innovative Engineering for Health award by the `Wellcome Trust`_\n[WT101957], the `Engineering and Physical Sciences Research Council (EPSRC)`_ [NS/A000027/1] and a\n`National Institute for Health Research`_ Biomedical Research Centre `UCLH`_/UCL High Impact Initiative.\n\n\n.. _`National Institute for Health Research`: http://www.nihr.ac.uk\n.. _`UCLH`: http://www.uclh.nhs.uk\n.. _`Engineering and Physical Sciences Research Council (EPSRC)`: http://www.epsrc.ac.uk\n.. _`Wellcome Trust`: http://www.wellcome.ac.uk\n\n\n", 
    "lcname": "endocal", 
    "bugtrack_url": null, 
    "github": true, 
    "coveralls": false, 
    "name": "endocal", 
    "license": "BSD-3-Clause", 
    "travis_ci": false, 
    "github_project": "endocal", 
    "summary": "A cross-platform, compact GUI application for the optical distortion calibration of fluid-immersed endoscopes.", 
    "split_keywords": [
        "optical distortion calibration", 
        "endoscope", 
        "endoscopy", 
        "medical imaging", 
        "image processing", 
        "biomedical engineering", 
        "medical physics", 
        "image-guided interventions"
    ], 
    "author_email": "d.shakir@ucl.ac.uk", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2018-02-13T20:00:22", 
            "comment_text": "", 
            "python_version": "py2.py3", 
            "url": "https://pypi.python.org/packages/df/19/6a39110dee6a5684c12210b18876731179ec28792f6d4f9857e79d1e1db6/endocal-18.2.13-py2.py3-none-any.whl", 
            "md5_digest": "fb9d4652f230d0862036bbecac3b03d6", 
            "downloads": 0, 
            "filename": "endocal-18.2.13-py2.py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "df/19/6a39110dee6a5684c12210b18876731179ec28792f6d4f9857e79d1e1db6/endocal-18.2.13-py2.py3-none-any.whl", 
            "size": 5453318
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}