Ticket #9234: trac_9234_doc_texture-sl.patch

File trac_9234_doc_texture-sl.patch, 8.5 KB (added by slabbe, 10 years ago)
  • sage/plot/plot3d/texture.py

    # HG changeset patch
    # User Sebastien Labbe <slabqc at gmail.com>
    # Date 1276509106 -7200
    # Node ID a4ae88845c3ba8489378bb1d5228d66c64765379
    # Parent  fac8469db0d82a373cac0ae5a3e185454d0b1e08
    #9234 Bring doc coverage of plot/plot3d/texture.py to 100%
    
    diff --git a/sage/plot/plot3d/texture.py b/sage/plot/plot3d/texture.py
    a b uniq_c = 0 
    1616from sage.plot.colors import colors
    1717
    1818def is_Texture(x):
     19    r"""
     20    Return whether x is an instance of ``Texture_class``.
     21
     22    EXAMPLES::
     23
     24        sage: from sage.plot.plot3d.texture import is_Texture, Texture
     25        sage: t = Texture(0.5)
     26        sage: is_Texture(t)
     27        True
     28
     29    ::
     30
     31        sage: is_Texture(4)
     32        False
     33    """
    1934    return isinstance(x, Texture_class)
    2035
    2136def Texture(id=None, **kwds):
     37    r"""
     38    Return a texture.
     39
     40    INPUT:
     41
     42    - ``id`` - a texture (optional, default: None), a dict, a color, an
     43      str, a tuple, None or any other type acting as an ID. If ``id`` is
     44      None, then it returns a unique texture object.
     45    - ``texture`` - a texture
     46    - ``color`` - tuple or str, (optional, default: (.4, .4, 1))
     47    - ``opacity`` - number between 0 and 1 (optional, default: 1)
     48    - ``ambient`` - number (optional, default: 0.5)
     49    - ``diffuse`` - number (optional, default: 1)
     50    - ``specular`` - number (optional, default: 0)
     51    - ``shininess`` - number (optional, default: 1)
     52    - ``name`` - str (optional, default: None)
     53    - ``**kwds`` - other valid keywords
     54
     55    OUTPUT:
     56
     57    a texture object
     58
     59    EXAMPLES:
     60
     61    Texture from integer id::
     62
     63        sage: from sage.plot.plot3d.texture import Texture
     64        sage: Texture(17)
     65        Texture(17, 6666ff)
     66
     67    Texture from rational id::
     68
     69        sage: Texture(3/4)
     70        Texture(3/4, 6666ff)
     71
     72    Texture from dict::
     73
     74        sage: Texture({'color':'orange','opacity':0.5})
     75        Texture(texture..., orange, ffa500)
     76
     77    Texture from a color::
     78
     79        sage: c = Color('red')
     80        sage: Texture(c)
     81        Texture(texture..., ff0000)
     82
     83    Texture from a valid str color::
     84
     85        sage: Texture('red')
     86        Texture(texture..., red, ff0000)
     87
     88    Texture from a non valid str color::
     89
     90        sage: Texture('redd')
     91        Texture(redd, 6666ff)
     92
     93    Texture from a tuple::
     94
     95        sage: Texture((.2,.3,.4))
     96        Texture(texture..., 334c66)
     97
     98    Texture using other keywords::
     99
     100        sage: Texture(specular=0.4)
     101        Texture(texture..., 6666ff)
     102        sage: Texture(diffuse=0.4)
     103        Texture(texture..., 6666ff)
     104        sage: Texture(shininess=0.3)
     105        Texture(texture..., 6666ff)
     106        sage: Texture(ambiant=0.7)
     107        Texture(texture..., 6666ff)
     108    """
    22109    if isinstance(id, Texture_class):
    23110        return id
    24111    if kwds.has_key('texture'):
    def Texture(id=None, **kwds): 
    49136    return Texture_class(id, **kwds)
    50137   
    51138def parse_color(info, base=None):
     139    r"""
     140    Parse the color.
     141   
     142    It transforms valid color str into color object and
     143    color object into tuple of length 3. Otherwise, it multiplies the info
     144    by the base color.
     145
     146    INPUT:
     147
     148    - ``info`` - color, valid color str or number
     149    - ``base`` - tuple of length 3 (optional, default: None)
     150
     151    OUTPUT:
     152
     153    tuple or color
     154
     155    EXAMPLES:
     156
     157    From a color::
     158
     159        sage: from sage.plot.plot3d.texture import parse_color
     160        sage: c = Color('red')
     161        sage: parse_color(c)
     162        (1.0, 0.0, 0.0)
     163
     164    From a valid color str::
     165
     166        sage: parse_color('red')
     167        RGB color (1.0, 0.0, 0.0)
     168
     169    From a non valid color str::
     170
     171        sage: parse_color('redd')
     172        Traceback (most recent call last):
     173        ...
     174        ValueError: unknown color 'redd'
     175
     176    From an info and a base::
     177
     178        sage: opacity = 10
     179        sage: parse_color(opacity, base=(.2,.3,.4))
     180        (2.0, 3.0, 4.0)
     181    """
    52182    if isinstance(info, Color):
    53183        return info.rgb()
    54184    elif isinstance(info, str):
    def parse_color(info, base=None): 
    66196
    67197
    68198class Texture_class(SageObject):
    69     """
    70     We create a translucent texture:
     199    r"""
     200    Construction of a texture.
     201   
     202    See documentation of ``Texture`` for more details and examples.
     203
     204    EXAMPLES:
     205
     206    We create a translucent texture::
    71207
    72208        sage: from sage.plot.plot3d.texture import Texture
    73209        sage: t = Texture(opacity=0.6)
    class Texture_class(SageObject): 
    78214        sage: t.jmol_str('obj')
    79215        'color obj translucent 0.4 [102,102,255]'
    80216        sage: t.mtl_str()
    81         'newmtl texture2\nKa 0.2 0.2 0.5\nKd 0.4 0.4 1.0\nKs 0.0 0.0 0.0\nillum 1\nNs 1\nd 0.600000000000000'
    82         sage: t.tachyon_str()
    83         'Texdef texture2\n  Ambient 0.333333333333 Diffuse 0.666666666667 Specular 0.0 Opacity 0.600000000000000\n   Color 0.4 0.4 1.0\n   TexFunc 0'
     217        'newmtl texture23\nKa 0.2 0.2 0.5\nKd 0.4 0.4 1.0\nKs 0.0 0.0 0.0\nillum 1\nNs 1\nd 0.600000000000000'
    84218        sage: t.x3d_str()
    85219        "<Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1' specularColor='0.0 0.0 0.0'/></Appearance>"
    86220    """
    87221    def __init__(self, id, color=(.4, .4, 1), opacity=1, ambient=0.5, diffuse=1, specular=0, shininess=1, name=None, **kwds):
    88    
     222        r"""
     223        Construction of a texture.
     224       
     225        See documentation of ``Texture`` for more details and examples.
     226
     227        EXAMPLES::
     228
     229            sage: from sage.plot.plot3d.texture import Texture_class
     230            sage: Texture_class(3, opacity=0.6)
     231            Texture(3, 6666ff)
     232        """
    89233        self.id = id
    90234        if name is None and isinstance(color, str):
    91235            name = color
    class Texture_class(SageObject): 
    119263        EXAMPLES::
    120264       
    121265            sage: from sage.plot.plot3d.texture import Texture
    122             sage: Texture('yellow')
     266            sage: Texture('yellow')               #indirect doctest
    123267            Texture(texture..., yellow, ffff00)
    124268            sage: Texture((1,1,0), opacity=.5)
    125269            Texture(texture..., ffff00)
    class Texture_class(SageObject): 
    142286        return "%02x%02x%02x" % tuple(int(255*s) for s in self.color)
    143287       
    144288    def tachyon_str(self):
     289        r"""
     290        EXAMPLES::
     291
     292            sage: from sage.plot.plot3d.texture import Texture
     293            sage: t = Texture(opacity=0.6)
     294            sage: t.tachyon_str()
     295            'Texdef texture28\n  Ambient 0.333333333333 Diffuse 0.666666666667 Specular 0.0 Opacity 0.600000000000000\n   Color 0.4 0.4 1.0\n   TexFunc 0'
     296        """
    145297        total_color = float(sum(self.ambient) + sum(self.diffuse) + sum(self.specular))
    146298        if total_color == 0:
    147299            total_color = 1
    class Texture_class(SageObject): 
    155307        "   TexFunc 0"
    156308
    157309    def x3d_str(self):
     310        r"""
     311        EXAMPLES::
     312
     313            sage: from sage.plot.plot3d.texture import Texture
     314            sage: t = Texture(opacity=0.6)
     315            sage: t.x3d_str()
     316            "<Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1' specularColor='0.0 0.0 0.0'/></Appearance>"
     317        """
    158318        return "<Appearance><Material diffuseColor='%s %s %s' shininess='%s' specularColor='%s %s %s'/></Appearance>" % \
    159319                (self.color[0], self.color[1], self.color[2], self.shininess, self.specular[0], self.specular[0], self.specular[0])
    160320               
    161321    def mtl_str(self):
     322        r"""
     323        EXAMPLES::
     324
     325            sage: from sage.plot.plot3d.texture import Texture
     326            sage: t = Texture(opacity=0.6)
     327            sage: t.mtl_str()
     328            'newmtl texture2\nKa 0.2 0.2 0.5\nKd 0.4 0.4 1.0\nKs 0.0 0.0 0.0\nillum 1\nNs 1\nd 0.600000000000000'
     329        """
    162330        return "\n".join(["newmtl %s" % self.id,
    163331                   "Ka %s %s %s" % self.ambient,
    164332                   "Kd %s %s %s" % self.diffuse,
    class Texture_class(SageObject): 
    168336                   "d %s" % self.opacity, ])
    169337
    170338    def jmol_str(self, obj):
    171         """
    172         EXAMPLES:
     339        r"""
     340        INPUT:
     341
     342        - ``obj`` - str
     343
     344        EXAMPLES::
     345
     346            sage: from sage.plot.plot3d.texture import Texture
     347            sage: t = Texture(opacity=0.6)
     348            sage: t.jmol_str('obj')
     349            'color obj translucent 0.4 [102,102,255]'
     350           
     351        ::
     352
    173353            sage: sum([dodecahedron(center=[2.5*x, 0, 0], color=(1, 0, 0, x/10)) for x in range(11)]).show(aspect_ratio=[1,1,1], frame=False, zoom=2)
    174354        """
    175355        translucent = "translucent %s" % float(1-self.opacity) if self.opacity < 1 else ""