doc/salome/kernel_salome.dox

   1 /*!
   2
   3 \page kernel_salome Using salome.py module
   4
   5
   6 The Python module salome.py provides a functionality to access main
   7 SALOME features from the Python console (either embedded in GUI
   8 desktop or external one).
   9
  10 To use salome.py module, import it into the Python interpreter and
  11 initialize it by calling \c salome_init() function:
  12
  13 \code
  14 import salome
  15 salome.salome_init()
  16 \endcode
  17
  18 The salome.py Python module provides a set of variables and functions
  19 allowing access to different elements of the current SALOME
  20 session.
  21 This page gives a short description of most useful variables and
  22 functions.
  23
  24 \li \b orb Reference to the CORBA::ORB instance
  25
  26 This variable can be used to initialize different CORBA-related
  27 elements of the SALOME session (for example, naming service, etc).
  28 For example, to get an access to the SALOME naming service, you can
  29 use the following commands:
  30 \code
  31 import SALOME_NamingServicePy
  32 NS = SALOME_NamingServicePy.SALOME_NamingServicePy_i(salome.orb)
  33 \endcode
  34
  35 The \b orb variable is also useful when it is necessary to convert
  36 CORBA reference object to its string representation (IOR) and vice
  37 versa:
  38 \code
  39 studyIOR = salome.orb.object_to_string(salome.myStudy)
  40 study    = salome.orb.string_to_object(studyIOR)
  41 is_same  = salome.myStudy._is_equivalent(study) # is_same = True
  42 \endcode
  43
  44 \li \b naming_service SALOME naming service instance
  45
  46 This variable can be used to register/find objects created in a
  47 distributed environment. For example, to get access to the SALOME
  48 Module Catalog server, use \c Resolve() method:
  49 \code
  50 import SALOME_ModuleCatalog
  51 mc = salome.naming_service.Resolve('/Kernel/ModulCatalog')
  52 \endcode
  53
  54 Similarly, method \c Register() can be used to register objects
  55 in the naming service:
  56 \code
  57 salome.naming_service.Register(myObject,'/My/Object/Path')
  58 o = salome.naming_service.Resolve('/My/Object/Path')
  59 is_same = myObject._is_equivalent(o) # is_same = True
  60 \endcode
  61
  62 \li \b lcc Life Cycle CORBA class instance
  63
  64 This object can be used to get access to CORBA engine part of some
  65 SALOME module, available in the current SALOME session. The following
  66 code returns a reference to the Geometry module engine, loading it if
  67 necessary:
  68 \code
  69 import GEOM
  70 geom = salome.lcc.FindOrLoadComponent('FactoryServer', 'GEOM')
  71 \endcode
  72 \b Note, that in the above example, \e "FactoryServer" is a name of the
  73 SALOME container, where Geometry module engine should be loaded.
  74
  75 \anchor salome_myStudy
  76 \li \b myStudy Reference to the current (active) study
  77
  78 This variable can be used to manipulate with the date of the study:
  79 create data tree, assign attributes of different types to the objects
  80 in a data tree, create references between objects, etc.
  81
  82 \b Note, that the term "active" or "current" study does not make much
  83 sense outise the GUI Python console. When working in GUI, user always
  84 deals with one only top-level study, which desktop is currently on the
  85 top if the windows stack. This is what is called \e "active study".
  86 In TUI mode (without GUI or outside GUI), user has to manipulate with
  87 studies manually; no any special control for the life cycle of the
  88 study is done. In TUI mode, \c salome.muStudy variable is an instance
  89 of the first study created when you call salome_init() function.
  90
  91 The following code demonstrates some examples of \c salome.myStudy
  92 variable usage. For more details please refer to the SALOMEDS.idl file
  93 documentation.
  94
  95 \code
  96 # get study name
  97 studyName = salome.myStudy._get_Name()
  98
  99 # open study from file /home/user/MyStudy.hdf
 100 salome.myStudy.Open("/home/user/MyStudy.hdf")
 101
 102 # save study
 103 salome.myStudy.Save(False, False) # not using multifile save mode
 104
 105 # save study in ASCII format
 106 salome.myStudy.Save(True, True) # using multifile save mode
 107
 108 # save study with the new file path
 109 salome.myStudy.SaveAs("/home/user/MyStudy.hdf", False, False)
 110
 111 # save study with the new file path in ASCII format
 112 salome.myStudy.SaveAs("/home/user/MyStudy.hdf", False, True)
 113
 114 # clear study
 115 salome.myStudy.Clear()
 116
 117 # init study
 118 salome.myStudy.Init()
 119
 120 # find SALOMEDS component by its type
 121 scomponent = FindComponent("MyComponent")
 122
 123 # find SALOMEDS component by its entry ID
 124 scomponent = FindComponentID("0:1:1") # "0:1:1" is a component ID
 125
 126 # find SALOMEDS object by its name (first found object is returned)
 127 sobject = salome.myStudy.FindObject("MyObject")
 128
 129 # find SALOMEDS object by its entry ID
 130 sobject = salome.myStudy.FindObjectID() # "0:1:1:1" is an object ID
 131
 132 # find SALOMEDS object by its IOR attribute
 133 sobject = salome.myStudy.FindObjectIOR(IOR)
 134
 135 # find SALOMEDS object by its path in the data tree
 136 sobject = salome.myStudy.FindObjectByPath("/MyComponent/MyObject/MySubObject")
 137
 138 # get SALOMEDS object's path in a study data tree
 139 sobject_path = salome.myStudy.GetObjectPath(sobject)
 140
 141 # get study properties
 142 prop = salome.myStudy.GetProperties()
 143 prop.GetCreationDate() # get creation date
 144 prop.IsModified() # check if study has been modified (and not yet saved)
 145 prop.SetLocked(True) # lock the study (prohibit modifications)
 146 prop.IsLocked() # check if study is locked
 147
 148 # create objects with study builder
 149 builder = salome.myStudy.NewBuilder() # create builder
 150 comp = builder.NewComponent("MyComponent") # create a component of the "MyComponent" type
 151 attrName = builder.FindOrCreateAttribute(comp, "AttributeName")
 152 attrName.SetValue("MyComponent") # set name to the component
 153 object = builder.NewObject(comp) # create new object, a child of the component
 154 attrName = builder.FindOrCreateAttribute(object, "AttributeName")
 155 attrName.SetValue("MyObject") # set name to the object
 156 attrInt = builder.FindOrCreateAttribute(object, "AttributeInteger")
 157 attrInt.SetValue(123) # assign integer attribute to the object
 158 attrIOR = builder.FindOrCreateAttribute(object, "AttributeIOR")
 159 attrIOR.SetValue(IOR) # assign IOR attribute to the object (to point to some CORBA object)
 160
 161 # iterate through objects of the data tree with child iterator
 162 iter = salome.myStudy.NewChildIterator(comp) # initialize from the component
 163 iter.InitEx(True) # init recursive mode
 164 while iter.More():
 165       c = iter.Value()
 166       print c.GetID()
 167       iter.Next()
 168       pass
 169
 170 # ...
 171 \endcode
 172
 173 \li \b myStudyName Name of the current (active) study
 174
 175 This variable contains the name of the current (active) study. It is
 176 an equivalent of \c salome.myStudy._get_Name() code.
 177
 178 \li \b DumpStudy() Print study contents
 179
 180 This function prints the study data object tree to the terminal
 181 window. The output for each object includes its entry ID, name, IOR
 182 (if there is one) and referenced object ID (for references). I.e.
 183 this is the same data the user can see in the Object Browser columns.
 184 \code
 185 salome.DumpStudy()
 186 \endcode
 187
 188 \li \b IDToSObject() Get SALOMEDS object by its entry ID.
 189
 190 This function checks if the SObject with the specified entry ID exists
 191 in the current study and returns it. Otherwise \c None is returned.
 192 \code
 193 sobject = salome.IDToSObject("0:1:1:1") # "0:1:1:1" is an object ID
 194 \endcode
 195 Actually this function is just a shortcut to the following code:
 196 \code
 197 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 198 \endcode
 199
 200 \li \b IDToObject() Get CORBA object by its entry ID.
 201
 202 This function checks if the SObject with the specified entry ID exists
 203 in the current study, then retrieves IOR attribute from it and,
 204 finally, if IOR is not empty, returns CORBA object corresponding to
 205 the found SObject:
 206 \code
 207 object = salome.IDToObject("0:1:1:1") # "0:1:1:1" is an object ID
 208 \endcode
 209 Actually this function is just a shortcut to the following code:
 210 \code
 211 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 212 if sobject:
 213    object = sobject.GetObject()
 214 else:
 215    object = None
 216 \endcode
 217
 218 \li \b ObjectToSObject() Get SALOMEDS object corresponding to the
 219 CORBA object.
 220
 221 This function finds an object in the current study which corresponds
 222 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 223 the CORBA object). If there is no corresponding SALOMEDS object in the
 224 study, \c None is returned:
 225 \code
 226 sobject = salome.ObjectToSObject(object)
 227 \endcode
 228 Actually this function is just a shortcut to the following code:
 229 \code
 230 ior = salome.orb.object_to_string(object)
 231 sobject = salome.myStudy.FindObjectIOR(ior)
 232 \endcode
 233
 234 \li \b ObjectToID() Get SALOMEDS object entry ID corresponding to the
 235 CORBA object.
 236
 237 This function finds an object in the current study which corresponds
 238 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 239 the CORBA object). If the object is found, its entry ID is returned,
 240 otherwise empty string is returned:
 241 \code
 242 entry = salome.ObjectToID(object)
 243 \endcode
 244 Actually this function is just a shortcut to the following code:
 245 \code
 246 ior = salome.orb.object_to_string(object)
 247 sobject = salome.myStudy.FindObjectIOR(ior)
 248 if sobject:
 249    entry = sobject.GetID()
 250 else:
 251    entry = ""
 252 \endcode
 253
 254 \li \b generateName() Generate unique name
 255
 256 This function adds random numerical suffix to the passed string
 257 parameter ("Study" by default) and returns the resulting string:
 258 \code
 259 name_1 = salome.generateName() # name_1 is something like "Study682"
 260 name_1 = salome.generateName("Obj") # name_1 is something like "Obj32"
 261 \endcode
 262
 263 \li \b GetComponentVersion() Get version of component data stored in
 264 the study
 265
 266 This function allows to obtain the version of the component data
 267 stored in the current study.
 268 \note This function does not provide a current version of the
 269 component being used but that one initially stored in the study
 270 document.
 271
 272 The first parameter specifies the name of the component. If the
 273 specified component data is not stored in the study, the result value
 274 is "no component data". If the version of data is undefined, the
 275 result is "unknown".
 276
 277 The second parameter (\c False by default), when set to \c True,
 278 allows to retrieve all versions of the component data stored in the
 279 study. This is useful to check if version information is valid (the
 280 data might be updated and/or re-stored in %SALOME of versions different
 281 from initial one).
 282
 283 \code
 284 # get initial version of GEOM module data stored in the study
 285 geom_version = salome.GetComponentVersion('GEOM')
 286 # get all versions of GEOM module data stored in the study
 287 all_geom_versions = salome.GetComponentVersion('GEOM', True)
 288 \endcode
 289
 290 This function is introduced in %SALOME 6.6.0 (it does not work with
 291 studies created before version 6.6.0).
 292
 293 \note The study should be initialized before calling this function
 294 (see \ref salome_myStudy "salome.myStudy").
 295
 296 */