a
    ¦ˆc™  ã                   @   sì   d Z ddlZddlZddlmZ ddlZddlm	Z	m
Z
mZmZmZmZmZmZmZmZ G dd„ deƒZej e¡Zej ed¡Zej ed¡Zeed	d
ej ¡ dd�Zed ejej  ¡ ¡ƒ ej!dd� "¡ Z#ed e#ej$ d ¡ƒ dS )a‘	  
Documentation
=============

Another advantage of using Traits is that you code becomes clearer and easier
for yourself and other people to work with.  If you look at the original
version of the image class, it isn't clear what attributes are available on
the class and, worse yet, it isn't clear *when* those attributes are available.

Self-Documenting Code
---------------------

By using Traits, all your attributes are declared up-front, so anyone reading
your class knows exactly what your class is providing::

    class Image(HasTraits):
        filename = File(exists=True)
        sample_id = Str()
        operator = Str("N/A")
        date_acquired = Date()
        scan_size = Tuple(Float, Float)
        scan_width = Property(Float, depends_on='scan_size')
        scan_height = Property(Float, depends_on='scan_size')
        image = Array(shape=(None, None), dtype='uint8')
        pixel_area = Property(Float, depends_on='scan_height,scan_width,image')
        histogram = Property(Array, depends_on='image')

This goes a long way towards the ideal of "self-documenting code."  It is
common in production-quality Traits code to also document each trait with a
special ``#:`` comment so that auto-documentation tools like Sphinx can
generate API documentation for you::

    class Image(HasTraits):

        #: The filename of the image.
        filename = File(exists=True)

        #: The ID of the sample that is being imaged.
        sample_id = Str()

        #: The name of the operator who acquired the image.
        operator = Str("N/A")

        ...


HasStrictTraits
---------------

One common class of errors in Python are typos when accessing an attribute
of a class.  For example, if we typed::

    >>> image.fileanme = "sample_0002.png"

Python will not throw an error, but the code will not have the effect that
the user expects.  Some development tools can help you detect these
sorts of errors, but most of these are not available when writing code
interactively, such as in a Jupyter notebook.

Traits provides a special subclass of ``HasTraits`` called ``HasStrictTraits``
which restricts the allowed attributes to **only** the traits on the class.
If we use::

    class Image(HasStrictTraits):
        ...

then if we type::

    >>> image.fileanme = "sample_0002.png"
    TraitError: Cannot set the undefined 'fileanme' attribute of a 'Image'
    object.

We get an immediate error which flags the problem.

é    N)ÚImage)
ÚArrayÚDateÚFileÚFloatÚHasStrictTraitsÚPropertyÚStrÚTupleÚcached_propertyÚobservec                   @   sÒ   e Zd ZdZedd�Zeƒ ZedƒZe	ƒ Z
eeeƒZeedd�Zeedd�Zeddd	�Zeed
d�Zeedd�Zd$dd„Zedƒdd„ ƒZdd„ Zdd„ Zdd„ Zdd„ Zdd„ Zdd„ Zdd „ Zed!d"„ ƒZ d#S )%r   z  An SEM image stored in a file. T)ÚexistszN/AÚ	scan_size)Z
depends_on)NNZuint8)ÚshapeZdtypezscan_height,scan_width,imageÚimager   éÿ   c                 C   s   | j |k| j |k@ S )z) Compute a threshold mask for the array. )r   )ÚselfÚlowÚhigh© r   úo/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/traits/examples/introduction/5_documentation.pyÚ	threshold„   s    zImage.thresholdÚfilenamec                 C   s"   t  | j¡ d¡}t |¡| _d S )NÚL)ÚPILImageÚopenr   ÚconvertÚnpÚarrayr   )r   ÚeventZ	pil_imager   r   r   Ú
read_imageŠ   s    zImage.read_imagec                 C   s
   t j ¡ S )N)ÚdatetimeÚdateÚtoday©r   r   r   r   Ú_date_acquired_default‘   s    zImage._date_acquired_defaultc                 C   s   dS )N©çñhãˆµøä>r'   r   r$   r   r   r   Ú_scan_size_default”   s    zImage._scan_size_defaultc                 C   s
   | j d S ©Nr   ©r   r$   r   r   r   Ú_get_scan_width™   s    zImage._get_scan_widthc                 C   s   || j d f| _ d S ©Né   r*   ©r   Úvaluer   r   r   Ú_set_scan_widthœ   s    zImage._set_scan_widthc                 C   s
   | j d S r,   r*   r$   r   r   r   Ú_get_scan_heightŸ   s    zImage._get_scan_heightc                 C   s   | j d |f| _ d S r)   r*   r.   r   r   r   Ú_set_scan_height¢   s    zImage._set_scan_heightc                 C   s(   | j jdkr | j| j | j j S dS d S r)   )r   ÚsizeÚscan_heightÚ
scan_widthr$   r   r   r   Ú_get_pixel_area¥   s    zImage._get_pixel_areac                 C   s   t j| jdddd�\}}|S )Né   )r   r7   T)ÚbinsÚrangeZdensity)r   Ú	histogramr   )r   Úhistr8   r   r   r   Ú_get_histogram«   s    ü
zImage._get_histogramN)r   r   )!Ú__name__Ú
__module__Ú__qualname__Ú__doc__r   r   r	   Ú	sample_idÚoperatorr   Údate_acquiredr
   r   r   r   r5   r4   r   r   Ú
pixel_arear:   r   r   r    r%   r(   r+   r0   r1   r2   r6   r   r<   r   r   r   r   r   c   s.   



r   Zimageszsample_0001.pngZHannesZ0001r&   )r   rB   rA   rC   r   z!The maximum intensity of {} is {}éÈ   )r   u9   The area with intensity greater than 200 is {:0.3f} ÂµmÂ²g   ¢”mB)%r@   Úosr!   ZPILr   r   Únumpyr   Z
traits.apir   r   r   r   r   r   r	   r
   r   r   ÚpathÚdirnameÚ__file__Zthis_dirÚjoinZ	image_dirr   r#   r   ÚprintÚformatrA   r:   Zargmaxr   ÚsumZpixel_countrD   r   r   r   r   Ú<module>   s8   L0Wû	þÿÿÿ