{"id":17113098,"url":"https://github.com/emmt/andorcameras.jl","last_synced_at":"2025-04-09T21:51:59.755Z","repository":{"id":71510217,"uuid":"107716241","full_name":"emmt/AndorCameras.jl","owner":"emmt","description":"A Julia interface to Andor cameras","archived":false,"fork":false,"pushed_at":"2021-07-05T21:36:57.000Z","size":117,"stargazers_count":3,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T21:51:56.473Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emmt.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-20T19:06:26.000Z","updated_at":"2023-09-04T15:52:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"6143783f-6f2e-42d9-827e-e6b64acaa51f","html_url":"https://github.com/emmt/AndorCameras.jl","commit_stats":{"total_commits":88,"total_committers":2,"mean_commits":44.0,"dds":"0.011363636363636354","last_synced_commit":"09f648a3386c45269372d0b425227e5d7ec204e4"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmt%2FAndorCameras.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmt%2FAndorCameras.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmt%2FAndorCameras.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmt%2FAndorCameras.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emmt","download_url":"https://codeload.github.com/emmt/AndorCameras.jl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119402,"owners_count":21050754,"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":[],"created_at":"2024-10-14T17:03:01.963Z","updated_at":"2025-04-09T21:51:59.734Z","avatar_url":"https://github.com/emmt.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A Julia interface to Andor cameras\n\nThis [Julia](http://julialang.org/) package implements an\n[interface](https://github.com/emmt/ScientificCameras.jl) to some\n[Andor cameras](http://www.andor.com/scientific-cameras) via the Andor Software\nDevelopment Kit (SDK).  As of version 3.13 of the SDK, the *Neo*, *Zyla*,\n*Apogee* and *iStar-SCMOS* Andor cameras should be supported.  The\n`AndorCameras` package has been tested on under Linux on the *Zyla* (USB-3\nconnected) camera, I am interested in feedback about other models.\n\nThis document describes:\n\n* the [standard interface](#standard-interface) which implements all the\n  methods specified by the\n  [`ScientificCameras`](https://github.com/emmt/ScientificCameras.jl)\n  interface;\n\n* the [advanced interface](#advanced-interface) which provides access to all\n  Andor cameras *features* and commands;\n\n* the [installation](#installation) of the\n  [`AndorCameras`](https://github.com/emmt/AndorCameras.jl) package.\n\n\n## Standard interface\n\nTo use the `AndorCameras` package, just write:\n\n```julia\nusing AndorCameras\n```\n\nwhich provides all the methods specified by the\n[`ScientificCameras`](https://github.com/emmt/ScientificCameras.jl) interface.\nThis interface is fully documented\n[here](https://github.com/emmt/ScientificCameras.jl) and summarized below.\n\nYou may also want to:\n\n```julia\nusing AndorCameras.Features\n```\n\nto use the [advanced interface](#advanced-usage).\n\n\n### Open and close a camera\n\nTo open an Andor camera:\n\n```julia\ncam = open(AndorCameras.Camera, dev)\n```\n\nwith `dev` the device number (`0` is the first device).  To figure out how many\nAndor devices are available:\n\n```julia\nAndorCameras.getnumberofdevices()\n```\n\nTo disconnect a camera from the hardware:\n\n```julia\nclose(cam)\n```\n\nNote that this is automatically done when the camera instance is claimed by the\ngarbage collector.\n\n\n### Configure a camera\n\n#### Region of interest\n\nA region of interest (ROI) may be selected by:\n\n```julia\nsetroi!(cam, [[xsub, ysub,] xoff, yoff,] width, height)\n```\n\nwhere `xsub` and `ysub` are the dimensions of the macro-pixels (in pixels and\nboth assumed to be `1` if not specified), `xoff` and `yoff` are the offsets of\nthe ROI relative to the sensor (in pixels and both assumed to be `0` if not\nspecified), `width` and `height` are the dimensions of the ROI (in\nmacro-pixels).\n\n*Macro-pixels* are blocks of `xsub` by `ysub` pixels when rebinning the pixels\nof the sensor.\n\nIn the Andor SDK documentation, the rebinning [features](#features) are\n`AOIHBin` and `AOIVBin`, the offsets (plus one) are `AOILeft` and `AOITop` and\nthe dimensions of the ROI are `AOIWidth` and `AOIHeight`.\n\nTo query the current ROI call:\n\n```julia\nroi = getroi(cam)\n```\n\nand to reset the ROI to use the full sensor with no rebinning, call:\n\n```julia\nresetroi!(cam)\n```\n\nThe full dimensions (in pixels) of the sensor are retrieved by:\n\n```julia\nfullwidth = getfullwidth(cam)\nfullheight = getfullheight(cam)\n```\n\nor by:\n\n```julia\nfullwidth, fullheight = getfullsize(cam)\n```\n\n\n#### Frame rate and exposure time\n\nThe `setspeed!` method let you choose the frame rate (`fps` in Hz) and the\nexposure time (`exp` in seconds) for the captured images:\n\n```julia\nsetspeed!(cam, fps, exp)\n```\n\nTo retrieve the actual values of these parameters:\n\n```julia\nfps, exp = getspeed(cam)\n```\n\n\n### Acquire a sequence of images\n\nTo acquire a single image (with the current settings):\n\n```julia\nimg = read(cam)\n```\n\nwhich yield an image in the form of a 2D Julia array.  To acquire a sequence of\n`n` images:\n\n```julia\nimgs = read(cam, n)\n```\n\nwhich yields a vector of images: `imgs[1]`, `imgs[2]`, ..., `imgs[n]`.  The\nreturned images are Julia 2D arrays of same dimensions as the selected region\nof interest (ROI) and whose element type is derived from the pixel format of\nthe camera as given by:\n\n```julia\ngetcapturebitstype(cam)\n```\n\nYou may specify another element type, say `T`, for the acquired images:\n\n```julia\nimg = read(cam, T)\n```\n\nor\n\n```julia\nimgs = read(cam, T, n)\n```\n\nbut there may be restrictions.\n\nThe `read` methods have the following keywords:\n\n* Use keyword `skip` to specify a number of images to skip.\n\n* Use keyword `timeout` to specify the maximum amount of time (in seconds) to\n  wait for acquisition to complete.  If acquisition takes longer than this\n  time, a `ScientificCameras.TimeoutError` is thrown unless keyword `truncate`\n  is `true` (see below).  The default timeout is computed from the acquisition\n  rate and the total number of images.\n\n* When reading a sequence of images, keyword `truncate` may be set `true` to\n  print a warning and return a truncated sequence instead of throwing an\n  exception in case of timeout.\n\n* Keyword `quiet` can be set `true` to suppress the printing of warning\n  messages (see above).\n\n\n### Continuous acquisition of images\n\nContinuous acquisition (and processing) of images is typically done by:\n\n```julia\nstart(cam, nbufs) # start continuous acquisition with `nbufs` cyclic buffers\nwhile ! finished()\n    img, ticks = wait(cam, sec) # wait for next image, not longer than `sec` seconds\n    ... # process the image\n    release(cam) # release the processed image\nend\nstop(cam)  # stop acquisition\n```\n\nwhere it is assumed that `finished()` returns `true` when to stop and `false`\notherwise.  Above, `img` is a 2D Julia array with the last captured image and\n`ticks` is the corresponding timestamp in seconds.  Releasing the captured\nimage with `release(cam)` when it has been processed is intended to recycle the\nimage buffer for another acquisition.  When the returned image is independent\nfrom the corresponding capture buffer, `release(cam)` does nothing.  It is\nnevertheless good practice to call this method when the captured image is no\nlonger needed because the code is more likely to work with no changes with\nanother camera.\n\nYou may specify another element type, say `T`, for the captured images:\n\n```julia\nstart(cam, T, nbufs)\n```\n\n\n## Advanced interface\n\nThis section describes advanced use of the interface to Andor cameras provided\nby the `AndorCameras` module.  This may be useful to perform specific\nconfiguration or actions not covered by the general interface.  Dealing with\nall the [*features*](#features) of Andor cameras is greatly simplified by the\nprovided Julia interface.\n\n\n### Constants\n\nThe constants defined in `atcore.h` are available in Julia, for instance\n`AndorCameras.AT_SUCCESS`.  All constants are prefixed with `AT_` and may be\nimported by:\n\n```julia\nusing AndorCameras.Constants\n```\n\nso that you just have to write `AT_SUCCESS` instead of\n`AndorCameras.AT_SUCCESS`.\n\n\n### Features\n\nAndor cameras have *features* whose value can be retrieved or set using the\narray index syntax:\n\n```julia\ncam[key]\ncam[key] = val\n```\n\nwhere `cam` is the camera instance, `key` is the considered feature and `val`\nits value.  Here `key` can be something like `AndorCameras.SensorWidth` or\njust `SensorWidth` if you have imported all defined features by:\n\n```julia\nusing AndorCameras.Features\n```\n\nFor instance:\n\n```julia\nusing AndorCameras.Features\nsensorwidth = cam[SensorWidth]\nsensorheight = cam[SensorHeight]\n```\n\nyields the full dimensions of the sensor of camera `cam`.\n\nThe names of the constants defining the existing features closely follow the\n*Andor Software Development Kit* documentation.  This documentation should be\nconsulted to figure out the supported features and their meaning.  If specific\nfeatures are missing, it is easy to [define new ones](#define-new-features).\n\nJulia `AndorCameras` module takes care of the different kind of features\ndepending on the type of their values: integer, floating-point, string,\nboolean or enumerated.  Enumerated features can take integer or string\nvalues, they are described [below](#enumerated-features).  There are also\n[*command* features](#commands) which have no value but are used to send\ncommands to the camera.\n\nTo query whether a specific feature is implemented, or whether it is readable,\nwritable or read-only, do one of:\n\n```julia\nisimplemented(cam, key)\nisreadable(cam, key)\niswritable(cam, key)\nisreadonly(cam, key)\n```\n\nInteger and floating-point features may have restrictions on the allowed range\nof values.  The minimum and maximum allowed values can be retrieved by:\n\n```julia\nminimum(cam, key)\nmaximum(cam, key)\n```\n\n\n#### String representation\n\nA string representation of feature `key` is obtained by:\n\n```julia\nrepr(key)\n```\n\n\n#### Enumerated features\n\nAn enumerated feature can only have a limited number of predefined values.\nThese values can be set by an integer index or by their name.  Assuming\n`cam` is the camera instance:\n\n```julia\ncam[key] = idx\n```\n\nor:\n\n```julia\ncam[key] = str\n```\n\nwith `key` the enumerated feature, *e.g.* `PixelEncoding`, `idx` and `str`\nthe index and the name of the chosen value.  The following expression:\n\n```julia\ncam[key]\n```\n\nyields the current index of the enumerated feature.  Note that enumeration\nindices start at `1` (as do indices in Julia).  The minimum and maximum\nindices are respectively given by:\n\n```julia\nminimum(cam, key)\nmaximum(cam, key)\n```\n\nthe former always yields `1` for an enumerated feature.\n\nTo retrieve the string representation of the value an enumerated feature, do\none of:\n\n```julia\nrepr(cam, key)\nrepr(cam, key, idx)\n```\n\nwhich respectively yield the string representation of the current value of the\nenumerated feature and of the value at a given index.\n\nTo query whether a given index is available or implemented for an enumerated\nfeature, call respectively:\n\n```julia\nisavailable(cam, key, idx)\nisimplemented(cam, key, idx)\n```\n\n\n#### Commands\n\nCommand features (*e.g.* `AcquisitionStart`) are used to identify a specific\ncommand to send to the camera.  These features have no values.  To send the\ncommmand `cmd` to the camera `cam`, you just have to:\n\n```julia\nsend(cam, cmd)\n```\n\n\n#### Define new features\n\nIf specific features are not predefined by the `AndorCameras` package, you may\ndefine them at run-time provided their name and type is known.  For instance:\n\n```julia\nboolkey = AndorCameras.BooleanFeature(\"SomeBooleanFeature\")\nintkey = AndorCameras.IntegerFeature(\"SomeIntegerFeature\")\nenumkey = AndorCameras.EnumeratedFeature(\"SomeEnumeratedFeature\")\nfltkey = AndorCameras.FloatingPointFeature(\"SomeFloatingPointFeature\")\nstrkey = AndorCameras.StringFeature(\"SomeStringFeature\")\n```\n\nwould define 5 features of 5 different types given their names.  These features\ncan be used as any others.  For instance:\n\n```julia\ncam[boolkey] = false\n```\n\nIf performance and readability are not an issue, a feature may be defined on\nthe fly.  For instance:\n\n```julia\ncam[AndorCameras.BooleanFeature(\"SomeBooleanFeature\")] = false\n```\n\n\n## Installation\n\nThe easiest way to install `AndorCameras` is via the Julia registry\n[`EmmtRegistry`](https://github.com/emmt/EmmtRegistry):\n\n```julia\nusing Pkg\npkg\"registry add https://github.com/emmt/EmmtRegistry\"\npkg\"add AndorCameras\"\npkg\"build AndorCameras\"\n```\n\nThe build process assumes that [Andor Software Development Kit\n(SDK)](http://www.andor.com/scientific-software/software-development-kit) has\nbeen installed in the usual directory `/usr/local/andor` for Linux or\n`C:/Program Files/AndorSDK3` for Windows (read the end of this section if you\nhave installed the SDK elsewhere).\n\nIf Andor SDK is not installed in the usual directory, you can define the\n`AT_DIR`, `AT_INCDIR` and/or `AT_LIBDIR` environment variables before building\n`AndorCameras`.  These variables are used as follows:\n\n* `AT_DIR` is the directory where the Andor SDK has been installed.  If this\n  environment variable is not defined, it is assumed to be `/usr/local/andor`\n  for Linux or `C:/Program Files/AndorSDK3` for Windows.\n\n* `AT_INCDIR` is the directory containing the Andor SDK header file `atcore.h`.\n  If this environment variable is not defined, the header file is searched in\n  directories `$AT_DIR/include` and `$AT_DIR` (in that order).\n\n* `AT_LIBDIR` is the directory containing the Andor SDK library (`libatcore.so`\n  on Linux, `atcore.dll` on Windows).  If this environment variable is not\n  defined, the library is searched in directories `$AT_DIR/lib` and `$AT_DIR`\n  (in that order).\n\nFor instance id Andor SDK has been installed in `/opt/andor`, you can define\nthe `AT_DIR` environment variable in Julia by:\n\n```julia\nENV[\"AT_DIR\"] = \"/opt/andor\"\n```\n\nbefore building `AndorCamera`:\n\n```julia\nusing Pkg\npkg\"build AndorCameras\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmt%2Fandorcameras.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femmt%2Fandorcameras.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmt%2Fandorcameras.jl/lists"}