Package: pca-b-stream
InstallationA Web app of PCA-B-Stream might be available onPythonAnywhere.This project is published
on thePython Package Index (PyPI)at:https://pypi.org/project/pca-b-stream/.
It should be installable from Python distribution platforms or Integrated Development Environments (IDEs).
Otherwise, it can be installed from a command console:For all users, after acquiring administrative rights:First installation:pip installpca-b-streamInstallation update:pip install--upgradepca-b-streamFor the current user (no administrative rights required):First installation:pip install--userpca-b-streamInstallation update:pip install--user--upgradepca-b-streamBrief DescriptionIn a Few WordsThePCA-B-Streamproject allows to generate a printablebyte streamrepresentation of a piecewise-constantNumpy array, and to re-create the array from the byte stream, similarly to what is available as part of theCOCO API.IllustrationIn Python:>>>importpca_b_streamaspcas>>>importnumpyasnmpy>>># --- Array creation>>>array=nmpy.zeros((10,10),dtype=nmpy.uint8)>>>array[1,1]=1>>># --- Array -> Byte stream -> Array>>>stream=pcas.PCA2BStream(array)>>>decoding=pcas.BStream2PCA(stream)>>># --- Check and print>>>assertnmpy.array_equal(decoding,array)>>>print(stream)b'FnmHoFain+3jtU'From command line:pca2bstreamsome_image_file# Prints the corresponding byte streambstream2pcaa_byte_streama_filename# Creates an image from the byte stream and stores itMotivationsThe motivations for developing an alternative to existing solutions are:Arrays can be of any dimension (i.e., not just 2-dimensional),Theirdtypecan be of boolean, integer, or float types,They can contain more than 2 distinct values (i.e., non-binary arrays) as long as the values are integers (potentially stored in a floating-point format though),The byte stream representation is self-contained; In particular, there is no need to keep track of the array shape externally,The byte stream representation contains everything needed to re-create the arrayexactlyas it was instantiated (dtype, endianness, C or Fortran ordering); Seenotethough.NoteThe statement “re-create the arrayexactlyas it was instantiated” is over-confident. First this has not been fully tested by, for example, re-creating an array on a another machine with a native endianness different from the one it was originally instantiated on. Second, more work might be required to ensure that enumeration ordering is correctly dealt with.DocumentationFunctionsThepca_b_streammodule defines the following functions:PCA2BStreamGenerates the byte stream representation of an array; Does not check the array validity (seePCArrayIssues)Input: aNumpy ndarrayOutput: an object of typebytesBStream2PCARe-creates the array from its bytes stream representation; Does not check the stream format validityInput/Output: input and output ofPCA2BStreamswappedPCArrayIssuesChecks whether an array is a valid input for stream representation generation; It is meant to be used before callingPCA2BStreamInput: aNumpy ndarrayOutput: a tuple issues instrformat. The tuple is empty if the array is valid.Additional information about what are valid piecewise-constant arrays here is provided in the section“Motivations”.BStreamDetailsExtract details from a byte stream representation; See section“Byte Stream Format”Inputs:a byte stream generated byPCA2BStreamdetails: a string where each character corresponds to a detail to extract, or “+” to extract all of the available details; Default: “+”; Available details are:c: compression indicatord: array dimensionl: array lengths per dimensiont: dtype type code; See:https://numpy.org/doc/stable/reference/generated/numpy.dtype.char.htmlT: dtype name; Translated from “t” by Numpy.sctypeDicto: enumeration order; See:https://numpy.org/doc/stable/reference/generated/numpy.ndarray.flags.html, ?_CONTIGUOUSe: endianness (or byte order); See:https://numpy.org/doc/stable/reference/generated/numpy.dtype.byteorder.htmlshould_print: a boolean to instruct whether the extracted details should be printed to console; Defaults: Falseshould_return: a boolean to instruct whether the extracted details should be returned (see Outputs); Defaults: TrueOutput: either one of:None if should_return is Falsea dictionary of all of the available details if thedetailsparameter is “+”a tuple of the requested details in the same order as in thedetailsparameterCommand Line ScriptsThePCA-B-Streamproject defines two command line scripts:pca2bstreamandbstream2pca. The former takes a path to an image file as argument, and prints the corresponding byte stream (without the “b” string type prefix). The latter takes a character string and a filename as arguments, in that order, and creates an image file with this name that corresponds to the string interpreted as a byte stream. The file must not already exist.Byte Stream FormatA byte stream is abase85-encodedstream. Once decoded, it has the following format (in lexicographical order; all characters are inbytesformat):one character “0” or “1”: indicates whether the remaining of the stream is in uncompressed orZLIB compressedformat; Seenote on compression; The remaining of the description applies to the stream in uncompressed format3 characters “{E}{T}{O}”:E: endianness among “|”, “<” and “>”T:dtypecharacter code among: “?” + numpy.typecodes[“AllInteger”] + numpy.typecodes[“Float”]O: enumeration order among “C” (C-ordering) and “F” (Fortran-ordering)one integer for the dimension of the array (1 for vectors, 2 for matrices, 3 for volumes…)one integer per dimension giving the length of the array in that dimensionThe remaining of the stream is the actual array content.If the array is not all False’s or zeros:one character “0” or “1”: whether the first value in the array is zero (or False) or one (or True)one integer for the length of the run-length representationintegers of therun-length representationof the array read in its proper enumeration orderIf the array is all False’s or zeros:one character “2”All the integers are encoded by theunsigned LEB128 encodingusing theleb128 project.For non-boolean arrays with a maximum value of 2 or more, the content part is the concatenation of the sub-contents corresponding to each value between 1 and the maximum value in the array.NoteFor small arrays, compressing the byte stream actually produces a longer stream.AcknowledgmentsThe project is developed withPyCharm Community.The development relies on several open-source packages
(seeinstall_requiresinsetup.py, if present; otherwiseimportstatements should be searched for).The code is formatted byBlack,The Uncompromising Code Formatter.The imports are ordered byisort…your imports, so you don’t have to.