{"id":22753634,"url":"https://github.com/slaclab/psgeom","last_synced_at":"2025-10-09T02:41:57.281Z","repository":{"id":84986440,"uuid":"37669424","full_name":"slaclab/psgeom","owner":"slaclab","description":"code for representing the geometry of scattering experiments","archived":false,"fork":false,"pushed_at":"2023-06-23T20:29:29.000Z","size":107365,"stargazers_count":2,"open_issues_count":8,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-04T03:02:13.582Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/slaclab.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-06-18T15:55:13.000Z","updated_at":"2021-02-09T21:00:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"29999043-fcbd-4773-9517-14b717865be6","html_url":"https://github.com/slaclab/psgeom","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/slaclab/psgeom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpsgeom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpsgeom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpsgeom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpsgeom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slaclab","download_url":"https://codeload.github.com/slaclab/psgeom/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpsgeom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000773,"owners_count":26082906,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-12-11T06:12:16.044Z","updated_at":"2025-10-09T02:41:57.245Z","avatar_url":"https://github.com/slaclab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# psgeom\n[![Build Status](https://travis-ci.org/slaclab/psgeom.svg?branch=master)](https://travis-ci.org/slaclab/psgeom)\n\npsgeom aims to provide an easy to use code base for common geometrical \noperations during scattering experiments:\n* load/save multiple geometry formats\n* translate/rotate parts of a detector\n* easily compute reciprocal/polar space coordinates\n* perform angular integration\n\nUser-friendliness is emphasized. The software aims to be general\nbut not sacrifice simplicity.\n\nChances are that if you need to compute stuff relating to scattering\ngeometry for a particular experiment, psgeom has what you need, and\nit will be easy to use.\n\nCurrently, interfaces exist to geometry formats from:\n* psana\n* CrystFEL\n* cheetah\n* DIALS\n* LCLS detector group metrologies\n* a simple flat text / HDF5 pixel map\n\nTJ Lane \u003cthomas.joseph.lane@gmail.com\u003e\n\n------\n\n## Scripts ##\n\nA lot of users just want to convert geometry files between different formats, or other simple tasks. To assist, psgeom provides a few command line scripts that will be of general interest:\n\n* `geoconv` : convert between geometry file formats\n* `geoQ` : quickly get reciprocal space coordinates for a geometry\n* `gainmk` and `gainconv` : for CSPAD gain files -- to make a new one and convert it's formatting, respectively\n\nRun any script with a `-h` flag to get more information\n\n------\n\n## Examples ##\nA few examples of how to use the code.\n\n### format conversions ###\n```python\nfrom psgeom import camera\n\ngeom = camera.CompoundAreaCamera.from_psana_file('1-end.data')\ngeom.to_crystfel_file('my_new.geom')\n```\n\n### looking at pixel positions ###\n```python\ngeom = camera.CompoundAreaCamera.from_crystfel_file('my.geom')\nprint(geom.xyz) # real-space xyz coords\n```\n\n### looking at things in basisgrid format ###\nBy \"basisgrid\", we mean a the geometry is described as a set of panels; each panel by a vector pointing\nto the first pixel to be read from memory, along with two vectors for the slow/fast scan directions.\n```python\nbg = geom.to_basisgrid()\nfor g in range(bg.num_grids):\n    print(bg.get_grid(g))\n```\n\n### radial averaging ###\n```python\nfrom psgeom import bin\n\nxyz = geom.xyz\n\nbeam_vector = np.array([0.0, 0.0, 1.0])     # assumed\nwavenumber = 2.0 * np.pi / wavelength       # inv A\n\nnorm = np.linalg.norm(xyz, axis=-1)\nS = xyz / norm[...,None] # unit vector\n\nq_xyz = wavenumber * (S - beam_vector)\nq_mag = np.linalg.norm(q_xyz, axis=-1)\n\nradavg = bin.Averager(q_mag, mask, n_bins=500)\n\n# data is raw detector data, Iq is radial average in q-coords\nIq1 = radavg(data1) \nIq2 = radavg(data2) \n...\n```\n\n### an easier way to compute reciprocal coords ###\n```python\nfrom psgeom import camera\nfrom psgeom import reciprocal\n\ngeom = camera.CompoundAreaCamera.from_crystfel_file('my.geom')\neV = 9500.0\nd = reciprocal.Geometry(geom, eV)\n\nd.xyz        # real space cart\nd.polar      # real space polar\nd.reciprocal # reciprocal cart\nd.recpolar   # reciprocal polar coords\n\n# compute interpolated values at specific intersection points\npix, intersect = d.compute_intersections(interp_vectors, 0) # 0 --\u003e grid_index\n```\n\n\n-------\n\n## How it works ##\n\nIn the scattering community, there are two principle paradigms in use for representing complex detector/experimental geometries: the \"basisgrid\" paradigm, and the \"elemental\" paradigm. `psgeom` implements *both*, which means it is both extremely powerful and capable of converting between formats that use either paradigm.\n\nThe \"basisgrid\" paradigm represents a geometry as a set of 2d planar sensors in 3d space. These sensors are represented by a position (`p`) vector that points to the first pixel of that panel to be read from memory. Two additional vectors correspond to the slow (`s`) and fast (`f`) scan directions, showing how to map a 2d array of data onto the sensor geometry. Used by, for example, crystFEL.\n\nThe \"elemental\" paradigm defines sensor components by hand, and then builds a more complicated sensor geometry by translating/rotating these elements with respect to one another, perhaps in a heirarchical fashion. This provides a bit extra power in terms of representing how rigid units move in space, as they are often correlated (e.g. mounted on a hard platform driven by motors in a beamline). Because the elements must be specified in software, this paradigm comes with additional complexity.\n\nIn reality all known x-ray and electron detectors to date (as of April 2020) are , composed of planar, 2d arrays of rectangular pixels. `psgeom` reflects this by emphasizing element definitions that correspond to this pattern; such elements are defined by their (1) pixel shape, (2) array size (n-by-m pixels), and (3) any gaps in the sensor surface. This allows for conversion between the \"elemental\" and \"basisgrid\" paradigms.\n\nA paper describing these formats and the mathematics behind them is in preparation\n\n-------\n\n### Quick Links ###\n\nInformation about the psana geometry:\nhttps://confluence.slac.stanford.edu/display/PSDM/Detector+Geometry\n\nList of high quality geometries generated by users and optical metrologies generated by LCLS:\nhttps://confluence.slac.stanford.edu/display/PSDM/Geometry+History\n\nCrystFEL Geometry:\nhttp://www.desy.de/~twhite/crystfel/manual-crystfel_geometry.html\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslaclab%2Fpsgeom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslaclab%2Fpsgeom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslaclab%2Fpsgeom/lists"}