B -,c' @s dZddlmZmZmZmZddlZddlZddlZ ddl m Z ddZ dd Z ed d ddd d d dZddZe je je je je je jdZddZddZddZededdZd+ddZddZd d!Zd"d#Z d$ej!ej"ej#Z$d%d&Z%d'd(Z&d)d*Z'dS),a utils ----- Utility functions used by the other modules in the mrcfile package. Functions --------- * :func:`data_dtype_from_header`: Work out the data :class:`dtype ` from an MRC header. * :func:`data_shape_from_header`: Work out the data array shape from an MRC header * :func:`mode_from_dtype`: Convert a :class:`numpy dtype ` to an MRC mode number. * :func:`dtype_from_mode`: Convert an MRC mode number to a :class:`numpy dtype `. * :func:`pretty_machine_stamp`: Get a nicely-formatted string from a machine stamp. * :func:`machine_stamp_from_byte_order`: Get a machine stamp from a byte order indicator. * :func:`byte_orders_equal`: Compare two byte order indicators for equal endianness. * :func:`normalise_byte_order`: Convert a byte order indicator to ``<`` or ``>``. * :func:`spacegroup_is_volume_stack`: Identify if a space group number represents a volume stack. )absolute_importdivisionprint_functionunicode_literalsN)IMAGE_STACK_SPACEGROUPcCs|j}t||jjS)a_Return the data dtype indicated by the given header. This function calls :func:`dtype_from_mode` to get the basic dtype, and then makes sure that the byte order of the new dtype matches the byte order of the header's ``mode`` field. Args: header: An MRC header as a :class:`numpy record array `. Returns: The :class:`numpy dtype ` object for the data array corresponding to the given header. Raises: :exc:`ValueError`: If there is no corresponding dtype for the given mode. )modedtype_from_modeZ newbyteorderdtype byteorder)headerrr ,lib/python3.7/site-packages/mrcfile/utils.pydata_dtype_from_header.srcCsnt|j}t|j}t|j}t|j}t|jrD|||||f}n&|jtkr`|dkr`||f}n |||f}|S)aReturn the data shape indicated by the given header. Args: header: An MRC header as a :class:`numpy record array `. Returns: The shape tuple for the data array corresponding to the given header. r)intnxnynzmzspacegroup_is_volume_stackispgr)r rrrrshaper r rdata_shape_from_headerEs       r )f2Zf4Zi1Zi2Zu1Zu2Zc8cCs2|jt|j}|tkr t|Std|dS)aReturn the MRC mode number corresponding to the given :class:`numpy dtype `. The conversion is as follows: * float16 -> mode 12 * float32 -> mode 2 * int8 -> mode 0 * int16 -> mode 1 * uint8 -> mode 6 (data will be widened to 16 bits in the file) * uint16 -> mode 6 * complex64 -> mode 4 Note that there is no numpy dtype which corresponds to MRC mode 3. Args: dtype: A :class:`numpy dtype ` object. Returns: The MRC mode number. Raises: :exc:`ValueError`: If there is no corresponding MRC mode for the given dtype. z3dtype '{0}' cannot be converted to an MRC file modeN)kindstritemsize_dtype_to_mode ValueErrorformat)r Z kind_and_sizer r rmode_from_dtypeas r$)rrrrrrcCs0t|}|tkrtt|Std|dS)aReturn the :class:`numpy dtype ` corresponding to the given MRC mode number. The mode parameter may be given as a Python scalar, numpy scalar or single-item numpy array. The conversion is as follows: * mode 0 -> int8 * mode 1 -> int16 * mode 2 -> float32 * mode 4 -> complex64 * mode 6 -> uint16 * mode 12 -> float16 Note that modes 3 and 101 are not supported as there is no matching numpy dtype. Args: mode: The MRC mode number. This may be given as any type which can be converted to an int, for example a Python scalar (``int`` or ``float``), a numpy scalar or a single-item numpy array. Returns: The :class:`numpy dtype ` object corresponding to the given mode. Raises: :exc:`ValueError`: If there is no corresponding dtype for the given mode. zUnrecognised mode '{0}'N)r_mode_to_dtypenpr r"r#)rr r rr sr cCsddd|DS)z7Return a human-readable hex string for a machine stamp. css|]}d|VqdS)z0x{:02x}N)r#).0Zbyter r r sz'pretty_machine_stamp..)join)machstr r rpretty_machine_stampsr,cCsP|ddkr|ddkrdS|ddkr8|ddkr8dSt|}td|d S) aReturn the byte order corresponding to the given machine stamp. Args: machst: The machine stamp, as a :class:`bytearray` or a :class:`numpy array ` of bytes. Returns: ``<`` if the machine stamp represents little-endian data, or ``>`` if it represents big-endian. Raises: :exc:`ValueError`: If the machine stamp is invalid. rDr)r-A<>zUnrecognised machine stamp: N)r,r")r+Z pretty_bytesr r rbyte_order_from_machine_stamps r2)r-r-rr)r0r0rr)r/r1=cCst|}t|S)axReturn the machine stamp corresponding to the given byte order indicator. Args: byte_order: The byte order indicator: one of ``=``, ``<`` or ``>``, as defined and used by numpy dtype objects. Returns: The machine stamp which corresponds to the given byte order, as a :class:`bytearray`. This will be either ``(0x44, 0x44, 0, 0)`` for little-endian or ``(0x11, 0x11, 0, 0)`` for big-endian. If the given byte order indicator is ``=``, the native byte order is used. Raises: :exc:`ValueError`: If the byte order indicator is unrecognised. )normalise_byte_order_byte_order_to_machine_stamp) byte_orderr r rmachine_stamp_from_byte_ordersr7cCst|t|kS)aWork out if the byte order indicators represent the same endianness. Args: a: The first byte order indicator: one of ``=``, ``<`` or ``>``, as defined and used by :class:`numpy dtype ` objects. b: The second byte order indicator. Returns: :data:`True` if the byte order indicators represent the same endianness. Raises: :exc:`ValueError`: If the byte order indicator is not recognised. )r4)abr r rbyte_orders_equalsr:cCs4|dkrtd||dkr0tjdkr,dSdS|S)aConvert a numpy byte order indicator to one of ``<`` or ``>``. Args: byte_order: One of ``=``, ``<`` or ``>``. Returns: ``<`` if the byte order indicator represents little-endian data, or ``>`` if it represents big-endian. Therefore on a little-endian machine, ``=`` will be converted to ``<``, but on a big-endian machine it will be converted to ``>``. Raises: :exc:`ValueError`: If ``byte_order`` is not one of ``=``, ``<`` or ``>``. )r/r1r3z'Unrecognised byte order indicator '{0}'r3littler/r1)r"r#sysr )r6r r rr4s r4cCsd|kodkSS)a Identify if the given space group number represents a volume stack. Args: ispg: The space group number, as an integer, numpy scalar or single- element numpy array. Returns: :data:`True` if the space group number is in the range 401--630. iivr )rr r rr s rr'c CsVyt|ot|Stk rPytdd|DStk rJdSXYnXdS)zECheck if a string is entirely composed of printable ASCII characters.css|]}|tkVqdS)N)printable_chars)r(charr r rr)#sz%is_printable_ascii..FN)r isprintableisasciiAttributeErrorallUnicodeDecodeError)string_r r ris_printable_asciisrEcCs4tj|ddd}t|s0dtdd|D}|S)zVConvert bytes into a printable ASCII string by removing non-printable characters. asciiignore)encodingerrorscss|]}t|r|VqdS)N)rE)r(sr r rr)-sz.printable_string_from_bytes..)bytesdecoderEr*list)Zbytes_rDr r rprintable_string_from_bytes(srOcCstjt|dddS)a7Convert a string to bytes. Even though this is a one-liner, the details are tricky to get right so things work properly in both Python 2 and 3. It's broken out as a separate function so it can be thoroughly tested. Raises: UnicodeError: If the input contains non-ASCII characters. rFstrict)rHrI)rencode)rDr r rbytes_from_string1s rR)r3)(__doc__Z __future__rrrrstringr<Znumpyr&Z constantsrrrdictr!r$Zint8Zint16Zfloat32Z complex64Zuint16Zfloat16r%r r,r2 bytearrayr5r7r:r4rZ ascii_lettersdigitsZ punctuationr=rErOrRr r r r s8 ! &