{"id":34606641,"url":"https://github.com/bcdev/beam-extapi","last_synced_at":"2026-05-22T23:32:54.603Z","repository":{"id":4780262,"uuid":"5932271","full_name":"bcdev/beam-extapi","owner":"bcdev","description":"A BEAM API for C/C++ and Python programmers","archived":false,"fork":false,"pushed_at":"2013-12-11T11:58:08.000Z","size":4059,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-09-09T14:16:28.610Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.brockmann-consult.de/beam-wiki/display/BEAM/BEAM+External+API","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-09-24T09:22:17.000Z","updated_at":"2023-04-26T13:55:23.000Z","dependencies_parsed_at":"2022-09-21T00:42:45.306Z","dependency_job_id":null,"html_url":"https://github.com/bcdev/beam-extapi","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/bcdev/beam-extapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdev%2Fbeam-extapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdev%2Fbeam-extapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdev%2Fbeam-extapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdev%2Fbeam-extapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcdev","download_url":"https://codeload.github.com/bcdev/beam-extapi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcdev%2Fbeam-extapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33376130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-22T21:56:13.512Z","status":"ssl_error","status_checked_at":"2026-05-22T21:56:10.769Z","response_time":265,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2025-12-24T13:56:33.721Z","updated_at":"2026-05-22T23:32:54.591Z","avatar_url":"https://github.com/bcdev.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"beam-extapi\n===========\n\nExternal APIs for BEAM\n\nHow to build the Python API\n---------------------------\n\n\nInstall `beampy` into your local Python installation:\n\n    python setup.py install\n\n\nThe setup.py script depends on the JDK_HOME environment variable.\n\nFor Windows installations only: This must be set to a 32-bit Java JDK (1.6 or 1.7).\n\n    SET JDK_HOME=%JDK32_HOME%\n\n\nTo use the BEAM Python API you need to set BEAM_HOME environment variable.\nOn Windows, the path needs to be modified, so the Java 32-bit JVM can be found by the Python interpreter.\nExample python scripts can be found in the examples directory. So, on Windows try something like:\n\n    SET BEAM_HOME=C:\\Users\\Norman\\beam-4.11.1\n    SET PATH=%JDK_HOME%\\jre\\bin\\server;%PATH%\n    cd examples\n    python beampy_ndvi.py \u003cfile\u003e\n\n\nFor Windows installations only: While running setup.py for package installations Python 2.7 (and 3.3, Norman) searches for an installed Visual Studio 2008.\nYou can trick Python to use newer Visual Studio by setting correct path in VS90COMNTOOLS environment variable before calling setup.py.\n(from http://stackoverflow.com/questions/6551724/how-do-i-point-easy-install-to-vcvarsall-bat)\n\nIf you have Visual Studio 2010 installed, execute\n\n    SET VS90COMNTOOLS=%VS100COMNTOOLS%\n\n\nor with Visual Studio 2012 installed (this is not working; at least not with our build server; reason is not known yet)\n\n    SET VS90COMNTOOLS=%VS110COMNTOOLS%\n\n\nBuild Windows native installer:\n\n    python setup.py bdist_wininst\n\n\nTranslation Rules\n-----------------\n\n### Class definitions\n\n*Java:*\n\n    package org.esa.beam.framework.datamodel;\n    ...\n    public class Product {\n        ...\n    }\n\n*Python translation:*\nA class definition is created in module `beampy`. The Java package path is ignored, as long as we don't encounter any naming clashes.\n\n    class Product:\n        ...\n\n*C translation:*\nWe currently use void pointers to represent Java classes in C:\n\n    typedef void* Product;    \n\n...knowing that this is not the best option since we have neither compile- nor runtime type checking this way.\n\n### Method definitions\n\n*Java:*\n\n    public class Product {\n        public String getName() {\n            ...\n        }\n        ...\n    }\n\n*Python translation:*\nFirst a global function definition is generated\n    \n    def Product_getName(product):\n        ...\n\nwhich is then used by a corresponding Python method:\n\n    class Product:\n        def getName(self):\n            ...\n\n*C translation:*\nThe simple class name is used as prefix, again Java package path omitted for simplicity:\n\n    char* Product_getName();\n\n\n\nVery helpful Developer Links\n----------------------------\n\n* Project on Github: https://github.com/bcdev/beam-extapi\n* Java Native Interface (JNI) website: http://docs.oracle.com/javase/7/docs/technotes/guides/jni/\n* JNI data types: http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html\n* JNI function reference: http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html\n* Python/C API reference: http://docs.python.org/py3k/c-api/\n* Python/C API tutorial: http://docs.python.org/py3k/extending/\n* Python/C argument parsing:  http://docs.python.org/py3k/c-api/arg.html\n* Microsoft *cl* Compiler: http://msdn.microsoft.com/en-us/library/vstudio/9s7c9wdw.aspx\n* IBM Java 5 Diagnostics Guide: http://publib.boulder.ibm.com/infocenter/javasdk/v5r0/\n\n\nC-Code Generation Considerations\n--------------------------------\n\n* Take care of String if used as parameter (--\u003e const char*) or return value (by reference: char*, int max_size). (done first option)\n* Don't forget to increase global reference count when returning objects from Java VM.  (done)\n* If we start from a limited number of API classes, we need to remove methods that have arguments for which no factory exists at all.\n* Need to find out which Java SE classes are used in parameter lists, but neither cannot retrieved nor instanciated.\n  --\u003e ApiInfo already known about this (ApiInfo.getUsedNonApiClasses()) , but not handled yet\n* How to treat method (array) parameters that\n** are input, output or both  (see Band.read/writePixels() methods)\n  --\u003e e.g. new parameter annotations: @In, @Out, @InOut, or simply @Const or @ReadOnly\n      or may need to define special translation rules for these methods that have this issue\n** are used as method return values (see Band.readPixels() methods)\n  --\u003e e.g. new annotation @Return, or @Reuse or @ReturnedIfNotNull\n* How to deal with object parameters in which a C string is passed (generator doesn't know, that a string object needs to be created),\n  for example Product.writeHeader(Object output)\n   --\u003e String_newString(), in Python: String.newString(s)\n* How to translate constants defined in Java classes?\n   --\u003e constants are already collected (--\u003e ApiInfo)\n* How to deal with same function names originating from overloaded Java methods   (see Band.readPixels() methods)\n   --\u003e renaming / ignoring overloads looked up from configuration file\n       if not in configuration file, numbering these\n* How to treat String parameters?\n  --\u003e Now: String s -\u003e const char* s\n* How to treat String return values?\n  --\u003e Now: A char* is returned, clients must free it\n      Alternative: return String object and offer\n         int beam_strlen(String s);\n         void beam_strcpy(String s, char* buf, int max_len);\n* How to treat generics?\n  --\u003e Fixed. Now \u003cT\u003e --\u003e \u003cObject\u003e and \u003cT extends C\u003e --\u003e C\n* How to treat (primitive, string \u0026 object) arrays parameters?\n  --\u003e IN:   float[] a --\u003e const float* aElems, int aLength\n  --\u003e OUT:  float[] a --\u003e float* aElems, int aLength\n* How to treat (primitive, string \u0026 object) return values?\n  --\u003e  float[] m() --\u003e float* m(int* resultArrayLength)\n* How to treat object collections lists, sets, maps?\n  --\u003e Not addressed so far\n* How to treat enums? (e.g. HistogramMatching)\n  --\u003e Not addressed so far\n* How to treat public fields? (e.g. GeoPos)\n  --\u003e Not addressed so far\n* How to treat Java SE classes: File, Date, Point, Rectangle, etc?\n  --\u003e Not addressed so far. One solution is to provide factories for these objects, e.g. in Python\n  class Rectangle:\n    def __init__(self, obj):\n        self._obj = obj\n    @staticmethod\n    def create(x, y, w, h):\n        Rectangle(Rectangle_create(x, y, w, h))\n\n    Where the global Rectangle_create() function is a defined in beampy.pyd (as BeamPyRectangle_create in C) and\n    delegates to the Rectangle_create() function in beam_capi.dll\n\n* How to make sure that JNI global refs are decreased/freed?\n  --\u003e Not addressed so far\n* Must treat thrown exceptions!\n  --\u003e Not addressed so far\n* Must throw OutOfMemoryError if malloc fails!\n  --\u003e Not addressed so far\n* How to deal with multi-threaded C/Python programs (specifically, what about 'env' pointer in JNI, it is a per-thread environment)\n  --\u003e Not addressed so far\n* Care: Check ALWAYS for possible null return values (many JNI functions may return null)\n  --\u003e Not addressed so far. Must throw Java exceptions.\n\nTo-do List Code Generation\n--------------------------\n\n* Python API: For C-function names used in Python types (not BEAM API fucntions), follow convention that is used in\n  Python native code, see Python.h and other includes e.g. bytearrayobject.h.\n* Done: Use BEAM_HOME env and auto-configure JVM parameters (use Util_listDir).\n* Make sure Python classes implement correctly: __eq__, __ne__, __hash__ ...\n* Generate usable documentation (Doxgen + PyDoc).\n* Handle reference counting JNI / Python/C.\n* Handle return parameters in Python (done in C).\n* Generate error handling code. Check all JNI and all Py return values.\n\nTo-do BEAM API doc\n------------------\n* Review and update API doc of all core classes\n* Remove all \"@version $Revision$ $Date$\"\n* Try to remove all HTML elements\n* Get rid of all this annoying console outputs when invoking BEAM API: SLF4J warnings, JAI plain Java error, GeoTools EPSG database creation\n\nDesign Considerations\n---------------------\n\nUse JNI types in C-interface?\n    Yes, because BEAM API is Java and as such it is much less verbose and more concise to reuse JNI types, and is also less work\n    No, because the C-API shall be independent of its implementation or origin\n\nDuplicate Java API (or parts) 1:1?  (e.g. any method in Java gets its C counterpart)\n    Yes, because the Java API docs can be reused for C API.\n    No, because a more concise C-API can be generated. And no, because changes in the Java API need to be reflected in the C API\n     which will introduce a lot of work (but maybe we can generate code).\n\nShall C API functions return string buffers that users have to release later?\n    Yes, otherwise the signature of Java counterparts is will be different, because by-reference arguments passing is required then.\n         E.g. instead of\n              char* name = get_name(obj);\n              ...\n              free(name);\n         we have\n              char name[81];\n              get_name(obj, name, 80);\n    No, because it is obvious that strings need to be freed on the users side.\n\nShall the API allow for modification of single structures elements that are passed as arguments by-reference?\n\n\nFrequently seen problems\n========================\n\nWindows VC++ using \"Debug\" configuration:\nFehler\t11\terror LNK1104: Datei \"python32_d.lib\" kann nicht geöffnet werden.\tC:\\Users\\Norman\\JavaProjects\\beam-extapi\\msvc\\beampy\\LINK\tbeampy\n\n--\u003e No solution; Google does not help. Must use Release configuration\n\nLinux 32/64\nFind a way to inject the 'libmawt.so' into the runtime path using cmake.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcdev%2Fbeam-extapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcdev%2Fbeam-extapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcdev%2Fbeam-extapi/lists"}