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 \li \b myStudyManager Reference to the study manager
  76
  77 SALOMEDS Study manager is used to manipulate with the studies: create,
  78 open, save, close. It also can be used to find the study by its
  79 numerical ID or name. The code below demonstrates main
  80 functionalities of a study manager:
  81 \code
  82 # create new study with the name "MyStudy"
  83 new_study = salome.myStudyManager.NewStudy("MyStudy")
  84
  85 # open study from file /home/user/MyStudy.hdf
  86 study = salome.myStudyManager.OpenStudy("/home/user/MyStudy.hdf")
  87
  88 # save study
  89 salome.myStudyManager.Save(study, False) # not using multifile save mode
  90
  91 # save study in ASCII format
  92 salome.myStudyManager.SaveASCII(study, True) # using multifile save mode
  93
  94 # save study with the new file path
  95 salome.myStudyManager.SaveAs("/home/user/MyStudy.hdf", study, False)
  96
  97 # save study with the new file path in ASCII format
  98 salome.myStudyManager.SaveAsASCII("/home/user/MyStudy.hdf", study, False)
  99
 100 # close study
 101 salome.myStudyManager.Close(study)
 102
 103 # get list of all opened studies
 104 studies = salome.myStudyManager.GetOpenStudies()
 105
 106 # find study by its numerical ID (integer value starting from 1)
 107 study = salome.myStudyManager.GetStudyByID(studyID)
 108
 109 # find study by its name
 110 study = salome.myStudyManager.GetStudyByName("/home/user/MyStudy.hdf")
 111
 112 # ...
 113 \endcode
 114
 115 \li \b myStudy Reference to the current (active) study
 116
 117 This variable can be used to manipulate with the date of the study:
 118 create data tree, assign attributes of different types to the objects
 119 in a data tree, create references between objects, etc.
 120
 121 \b Note, that the term "active" or "current" study does not make much
 122 sense outise the GUI Python console. When working in GUI, user always
 123 deals with one only top-level study, which desktop is currently on the
 124 top if the windows stack. This is what is called \e "active study".
 125 In TUI mode (without GUI or outside GUI), user has to manipulate with
 126 studies manually; no any special control for the life cycle of the
 127 study is done. In TUI mode, \c salome.muStudy variable is an instance
 128 of the first study created when you call salome_init() function.
 129
 130 The following code demonstrates some examples of \c salome.myStudy
 131 variable usage. For more details please refer to the SALOMEDS.idl file
 132 documentation.
 133
 134 \code
 135 # get study name
 136 studyName = salome.myStudy._get_Name()
 137
 138 # get study numerical ID
 139 studyID = salome.myStudy._get_StudyId()
 140
 141 # find SALOMEDS component by its type
 142 scomponent = FindComponent("MyComponent")
 143
 144 # find SALOMEDS component by its entry ID
 145 scomponent = FindComponentID("0:1:1") # "0:1:1" is a component ID
 146
 147 # find SALOMEDS object by its name (first found object is returned)
 148 sobject = salome.myStudy.FindObject("MyObject")
 149
 150 # find SALOMEDS object by its entry ID
 151 sobject = salome.myStudy.FindObjectID() # "0:1:1:1" is an object ID
 152
 153 # find SALOMEDS object by its IOR attribute
 154 sobject = salome.myStudy.FindObjectIOR(IOR)
 155
 156 # find SALOMEDS object by its path in the data tree
 157 sobject = salome.myStudy.FindObjectByPath("/MyComponent/MyObject/MySubObject")
 158
 159 # get SALOMEDS object's path in a study data tree
 160 sobject_path = salome.myStudy.GetObjectPath(sobject)
 161
 162 # get study properties
 163 prop = salome.myStudy.GetProperties()
 164 prop.GetCreationDate() # get creation date
 165 prop.IsModified() # check if study has been modified (and not yet saved)
 166 prop.SetLocked(True) # lock the study (prohibit modifications)
 167 prop.IsLocked() # check if study is locked
 168
 169 # create objects with study builder
 170 builder = salome.myStudy.NewBuilder() # create builder
 171 comp = builder.NewComponent("MyComponent") # create a component of the "MyComponent" type
 172 attrName = builder.FindOrCreateAttribute(comp, "AttributeName")
 173 attrName.SetValue("MyComponent") # set name to the component
 174 object = builder.NewObject(comp) # create new object, a child of the component
 175 attrName = builder.FindOrCreateAttribute(object, "AttributeName")
 176 attrName.SetValue("MyObject") # set name to the object
 177 attrInt = builder.FindOrCreateAttribute(object, "AttributeInteger")
 178 attrInt.SetValue(123) # assign integer attribute to the object
 179 attrIOR = builder.FindOrCreateAttribute(object, "AttributeIOR")
 180 attrIOR.SetValue(IOR) # assign IOR attribute to the object (to point to some CORBA object)
 181
 182 # iterate through objects of the data tree with child iterator
 183 iter = salome.myStudy.NewChildIterator(comp) # initialize from the component
 184 iter.InitEx(True) # init recursive mode
 185 while iter.More():
 186       c = iter.Value()
 187       print c.GetID()
 188       iter.Next()
 189       pass
 190
 191 # ...
 192 \endcode
 193
 194 \li \b myStudyId Identifier of the current (active) study
 195
 196 This variable contains the numerical identifier of the current
 197 (active) study. It is an equivalent of \c
 198 salome.myStudy._get_StudyId() code.
 199
 200 \li \b myStudyName Name of the current (active) study
 201
 202 This variable contains the name of the current (active) study. It is
 203 an equivalent of \c salome.myStudy._get_Name() code.
 204
 205 \li \b DumpStudy() Print study contents
 206
 207 This function prints the study data object tree to the terminal
 208 window. The output for each object includes its entry ID, name, IOR
 209 (if there is one) and referenced object ID (for references). I.e.
 210 this is the same data the user can see in the Object Browser columns.
 211 \code
 212 salome.DumpStudy(salome.myStudy)
 213 \endcode
 214
 215 \li \b IDToSObject() Get SALOMEDS object by its entry ID.
 216
 217 This function checks if the SObject with the specified entry ID exists
 218 in the current study and returns it. Otherwise \c None is returned.
 219 \code
 220 sobject = salome.IDToSObject("0:1:1:1") # "0:1:1:1" is an object ID
 221 \endcode
 222 Actually this function is just a shortcut to the following code:
 223 \code
 224 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 225 \endcode
 226
 227 \li \b IDToObject() Get CORBA object by its entry ID.
 228
 229 This function checks if the SObject with the specified entry ID exists
 230 in the current study, then retrieves IOR attribute from it and,
 231 finally, if IOR is not empty, returns CORBA object corresponding to
 232 the found SObject:
 233 \code
 234 object = salome.IDToObject("0:1:1:1") # "0:1:1:1" is an object ID
 235 \endcode
 236 Actually this function is just a shortcut to the following code:
 237 \code
 238 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 239 if sobject:
 240    object = sobject.GetObject()
 241 else:
 242    object = None
 243 \endcode
 244
 245 \li \b ObjectToSObject() Get SALOMEDS object corresponding to the
 246 CORBA object.
 247
 248 This function finds an object in the current study which corresponds
 249 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 250 the CORBA object). If there is no corresponding SALOMEDS object in the
 251 study, \c None is returned:
 252 \code
 253 sobject = salome.ObjectToSObject(object)
 254 \endcode
 255 Actually this function is just a shortcut to the following code:
 256 \code
 257 ior = salome.orb.object_to_string(object)
 258 sobject = salome.myStudy.FindObjectIOR(ior)
 259 \endcode
 260
 261 \li \b ObjectToID() Get SALOMEDS object entry ID corresponding to the
 262 CORBA object.
 263
 264 This function finds an object in the current study which corresponds
 265 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 266 the CORBA object). If the object is found, its entry ID is returned,
 267 otherwise empty string is returned:
 268 \code
 269 entry = salome.ObjectToID(object)
 270 \endcode
 271 Actually this function is just a shortcut to the following code:
 272 \code
 273 ior = salome.orb.object_to_string(object)
 274 sobject = salome.myStudy.FindObjectIOR(ior)
 275 if sobject:
 276    entry = sobject.GetID()
 277 else:
 278    entry = ""
 279 \endcode
 280
 281 \li \b createNewStudy() Create new study
 282
 283 This function can be used to create new SALOME study. Returns an ID of
 284 the created study.
 285 \code
 286 studyId = salome.createNewStudy()
 287 study   = salome.myStudyManager.GetStudyByID(s)
 288 \endcode
 289
 290 \li \b generateName() Generate unique name
 291
 292 This function adds random numerical suffix to the passed string
 293 parameter ("Study" by default) and returns the resulting string:
 294 \code
 295 name_1 = salome.generateName() # name_1 is something like "Study682"
 296 name_1 = salome.generateName("Obj") # name_1 is something like "Obj32"
 297 \endcode
 298
 299 */