{"id":16190632,"url":"https://github.com/tiagocoutinho/lima-toolbox","last_synced_at":"2025-04-07T14:28:05.430Z","repository":{"id":62576129,"uuid":"264494983","full_name":"tiagocoutinho/lima-toolbox","owner":"tiagocoutinho","description":"A box of tools to support Lima. ","archived":false,"fork":false,"pushed_at":"2021-05-01T14:15:27.000Z","size":403,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-13T21:08:42.184Z","etag":null,"topics":["cli","click","lima","toolbox","toolkit"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiagocoutinho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-16T17:56:59.000Z","updated_at":"2021-06-12T11:24:07.000Z","dependencies_parsed_at":"2022-11-03T17:34:08.811Z","dependency_job_id":null,"html_url":"https://github.com/tiagocoutinho/lima-toolbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagocoutinho%2Flima-toolbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagocoutinho%2Flima-toolbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagocoutinho%2Flima-toolbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagocoutinho%2Flima-toolbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiagocoutinho","download_url":"https://codeload.github.com/tiagocoutinho/lima-toolbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247668751,"owners_count":20976262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","click","lima","toolbox","toolkit"],"created_at":"2024-10-10T07:43:48.684Z","updated_at":"2025-04-07T14:28:05.410Z","avatar_url":"https://github.com/tiagocoutinho.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lima tool box\n\nA set of command line tools which hopefully ease the configuration and\ndevelopment of [Lima](http://github.com/esrf-bliss/lima) cameras.\n\n![Lima toolbox in action](doc/lima_toolbox.svg)\n\n## Installation\n\n**TL;DR**\n\nFrom within your favorite python environment, type:\n\n```pip install lima-toolbox[all]```\n\n\u003cbr/\u003e\nThe toolbox is composed of a core library and plug-ins for diverse set of\ncameras.\n\nThe core can be installed with:\n\n```pip install lima-toolbox```\n\nTo install support for specific camera(s) use (example):\n\n```pip install lima-toolbox[basler,eiger]```\n\nAt the end you can find a mini-catalog of the available cameras.\n\nPRs which implement new cameras (or improve, or fix existing ones) are most\nwelcome.\n\n## CLI\n\nProbably the most useful tool is the CLI. You can use it to discover cameras\non the network, display information about a specfic camera and even perform\nacquisitions.\n\nThe limatb CLI provides global commands like `scan` which are not camera specific.\nIn addtition, each camera provides its own set of sub-commands. They are accessible\nby typing `lima \u003ccamera\u003e \u003csub-command\u003e` (ex: `lima eiger --host=bl99eiger info`).\n\nTyping ```limatb --help``` will display help. Help is context sensitive, so\ntyping ```limatb basler --help``` will display help for the basler subset of\ncommands.\n\n### camera discovery\n\ncamera toolbox plug-ins which provides *scan* capability allow you to\ndiscover them by using the `scan` command:\n\n```console\n$ limatb scan --table-style=box_rounded\n\nBasler:\n╭──────────────┬──────────────────────────────┬───────────────────────┬───────────┬────────────┬───────────┬────────╮\n│    Class     │        Friendly name         │       Full name       │   Name    │ Serial Nb. │ User name │ Vendor │\n├──────────────┼──────────────────────────────┼───────────────────────┼───────────┼────────────┼───────────┼────────┤\n│ BaslerCamEmu │ Basler Emulation (0815-0000) │ Emulation (0815-0000) │ Emulation │ 0815-0000  │           │ Basler │\n├──────────────┼──────────────────────────────┼───────────────────────┼───────────┼────────────┼───────────┼────────┤\n│ BaslerCamEmu │ Basler Emulation (0815-0001) │ Emulation (0815-0001) │ Emulation │ 0815-0001  │           │ Basler │\n├──────────────┼──────────────────────────────┼───────────────────────┼───────────┼────────────┼───────────┼────────┤\n│ BaslerCamEmu │ Basler Emulation (0815-0002) │ Emulation (0815-0002) │ Emulation │ 0815-0002  │           │ Basler │\n╰──────────────┴──────────────────────────────┴───────────────────────┴───────────┴────────────┴───────────┴────────╯\n\nEiger:\n╭───────────┬───────────┬─────────────┬──────┬───────╮\n│   Host    │ Alias(es) │ Address(es) │ Port │  API  │\n├───────────┼───────────┼─────────────┼──────┼───────┤\n│ bl04eiger │           │ 172.95.4.11 │ 8000 │ 1.6.0 │\n╰───────────┴───────────┴─────────────┴──────┴───────╯\n\nMythenSLS:\n╭────────────┬─────────────┬──────┬────────┬──────────┬──────────┬───────────┬────────────╮\n│    Host    │     IP      │ Port │  Type  │ #Modules │ Settings │ Threshold │ Dyn. Range │\n├────────────┼─────────────┼──────┼────────┼──────────┼──────────┼───────────┼────────────┤\n│ bl04mythen │ 172.95.4.10 │ 1952 │ MYTHEN │    6     │ STANDARD │   9071    │     32     │\n╰────────────┴─────────────┴──────┴────────┴──────────┴──────────┴───────────┴────────────╯\n```\n\nHere you can see 3 simulated [Basler](https://github.com/esrf-bliss/lima-camera-basler) cameras, an\n[Eiger](https://github.com/esrf-bliss/lima-camera-eiger) camera and a [Mythen SLS](https://github.com/alba-synchrotron/sls-detector) camera are available.\n\n### Common camera commands\n\nAs mentioned above, each camera provides its own set of specific sub-commands.\nThe sub-commands `info` and `acquire` are common to all cameras (altough the specific\nsub-command options could vary).\n\nThe set of options which identify a camera are specific to each camera. For example,\nto identify an eiger you must provide the `--url=\u003chostname\u003e` option.\n\nNote that there is nothing enforcing a specific camera to implement any of the\ncommon sub-commands. But it is considered good taste if a plugin does it (for the sake\nof coherency).\n\nA camera plugin may optionally implement the `scan` command. It should provide the same\nresult as the global scan with results restricted to the camera type.\n\n#### Camera information\n\nBasic information about a camera can be retrieved with the `info` sub-command.\n\nExamples:\n\n```console\n$ limatb eiger --url=bl04eiger info\n    CurrImageType: 10\n     DefImageType: 10\nDetectorImageSize: \u003c3110x3269\u003e\n    DetectorModel: Dectris Eiger 9M\n     DetectorType: E-18-0102\n   InstrumentName: instrument\n     MaxImageSize: \u003c3110x3269\u003e\n        PixelSize: (7.5e-05, 7.5e-05)\n UserDetectorName: E-18-0102\n\n$ limatb mythensls --url bl04mythen info\n      CurrImageType   10\n       DefImageType   10\n  DetectorImageSize   \u003c7680x1\u003e\n      DetectorModel   Mythen-II\n       DetectorType   MythenSLS\n     InstrumentName   instrument\n       MaxImageSize   \u003c7680x1\u003e\n          PixelSize   (1.0, 1.0)\n   UserDetectorName   MythenSLS\n\n      Detector type   MYTHEN\n      Serial number   1719109785\n   Software version   1867412\n             Status   IDLE\n      Dynamic range   32\n   Energy threshold   9071\n      Exposure time   1.0\n   Number of frames   0\n   Number of cycles   0\n    Number of gates   0\n             Master   NO_MASTER\n    Synchronization   NONE\n             Timing   AUTO_TIMING\n Delay after triger   0.0\n            Readout   NORMAL_READOUT\n           Settings   STANDARD\n   External signals   ['GATE_OUT_ACTIVE_HIGH', 'TRIGGER_IN_RISING_EDGE', 'OFF',\n                       'OFF']\n```\n\n### Camera acquisition\n\nAquisitions can be made with the `acquire` sub-command.\n\nThe common options include `-nb-frames`, `--exposure-time`, `--latency-time`. You\ncan see the complete list of options with `lima \u003ccamera\u003e acquire --help`.\n\nHere is an example performing an acquisition on an eiger camera:\n\n![eiger acquisition](doc/eiger_acq.svg)\n\n## How to write a plug-in for your camera\n\nYou have two options:\n\n### 1. Add a plug-in extension to Lima-toolbox\n\nWrite a PR to this repo with the camera you intend to add. This should always be\npossible independently of the type of camera you are writing the plug-in for.\n\nLet's say you want to create a plugin for the\n[Simulator](http://github.com/esrf-bliss/lima-camera-simulator) camera.\n\nFirst, create a new file in `src/limatb/camera` called `simulator.py`.\nThe lima toolbox CLI uses the [click](https://click.palletsprojects.com) library\nto help create a powerful command line interface.\n\nTo create a `simulator` sub-command you can simply use the lima toolbox `camera`\ndecorator (which is a `click.group` helper) and write a function that should\nreturn a `Lima.Interface` object:\n\n```python\n# src/limatb/camera/simulator.py\n\nfrom limatb.cli import camera\nfrom Lima.Simulator import Camera, Interface\n\n\n@camera(name='simulator')\ndef simulator():\n    camera = Simulator.Camera()\n    interface = Interface(camera)\n    return interface\n```\n\nThe second and last thing to do is to register the new command in the lima\ntoolbox setup.py like this:\n\n```python\nextras_require = {\n    \"simulator\": []  #  add any extra python dependencies if necessary\n}\n\nsetup(\n    ...,\n    entry_points={\n        \"lima.cli.camera\": [\n            ...\n            \"Simulator = limatb.camera.simulator:simulator [simulator]\"\n        ]\n    }\n)\n```\n\nThat's it. Next time you install lima-toolbox there should be a `simulator`\ncamera available with the default `info` and `acquire` sub-commands available\n*out of the box*.\n\nCongratulations! You are now ready to make a PR to this repo with your new camera.\n\nRead further to find how to implement camera options, details about the camera\ndecorator and how to implement your own camera specific sub-commands.\n\nExamples of existing cameras can be found in the `src/limatb/camera` directory.\n\n#### Custom options\n\nIf you need to add any option to the command line to identify or configure your\ncamera you can do it using `click.option`. Here is an example extending the\nprevious one:\n\n```python\nimport click\n\n@camera(name='simulator')\n@click.option(\n   '--fill-type',\n   click.Choice(['gauss', 'diffraction'],\n   case_sensitive=False),\n   default='gauss')\ndef simulator(fill_type):\n    camera = Simulator.Camera()\n    interface = Interface(camera)\n    fill_type = getattr(Lima.Simulator.FrameBuilder, fill_type.capitalize())\n    frame_getter = camera.getFrameGetter()\n    frame_getter.setFillType(fill_type)\n    return interface\n```\n\n#### The `camera` decorator\n\nThe `@camera` decorator helper provides a `click.group` decorator enhanced with\nthe `info` and `acquire` sub-commands by default and the facility that the\nreturned interface gets inserted into the click context object\n`ctx.obj['interface']` which can be accessed by any camera sub-commands you\ndecide to implement.\n\nHere is an example on how to implement a specific sub-command:\n\n```python\n\n@simulator.command(\"initialize\")\n@click.pass_context\ndef initialize(ctx):\n    # Initialization code here\n    interface = ctx.obj['interface']\n```\n\n### scan command\n\nThe lima toolbox CLI implements global `scan` command which has the purpose\nof discovering all the cameras in the system.\n\nTo make the specific `scan` command of your system visible to the global scan\ncommand you need to register a scan function with the signature:\n\n```python\n[async] def scan(timeout: float = None) -\u003e beautifultable.BeautifulTable\n```\n\nand register the entry point in setup.py with:\n\n```python\nsetup(\n    ...,\n    entry_points={\n        \"lima.cli.camera.scan\": [\n            ...\n            \"Simulator = limatb.camera.simulator:scan [simulator]\"\n        ]\n    }\n)\n```\n\nThe scan function can have any name you which. You can provide a coroutine\n(with `async` keyword).\n\nIf now you type `lima scan` on the command line, it should execute the\nscan command of all registered cameras.\n\n\n### 2. Write a Lima-toolbox entry point in an external project\n\nAnother option, if your camera plugin is installable via a `setup.py`, is to apply the\nsame recipes above, where the only difference resides in implementing the code in your\nown python detector package and modifying your setup.py instead.\n\nAn example of a project which following this phylosophy is the\n[SLS Mythen](http://github.com/alba-synchrotron/sls-detector).\n\n## Supported cameras\n\n\n### Provided inside lima toolbox\n\n* [Basler](src/limatb/camera/basler.py)\n* [Eiger](src/limatb/camera/eiger.py)\n\n### Known third party cameras\n\n* [SLS Mythen](http://github.com/alba-synchrotron/sls-detector)\n\nFeel free to make a PR adding your own camera to this list. They are most welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagocoutinho%2Flima-toolbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiagocoutinho%2Flima-toolbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagocoutinho%2Flima-toolbox/lists"}