Working with Scenes & Inputs

note for detailed information about different scene modalities, check the scene types section kognic users as a kognic user, it is possible to specify client organization id to kognicioclient constructor to create scenes on behalf of a client organization creating scenes each scene resource has a create method that can be used to create a scene of the corresponding type it takes the corresponding scene model as input, so for example to create a cameras scene you would do the following from kognic io model scene cameras import cameras scene = cameras( ) created scene = client cameras create(cameras scene) scene uuid = created scene uuid as you can see, the create method returns the associated scene uuid , which can later be used to work with the scene at this point all files have been uploaded to the kognic platform and the scene starts to be pre processed when pre processing is finished, we say that the scene has been created refer to the /#scene status section for more information about the different scene statuses note that it is often useful to use the dryrun parameter when experimenting this will validate the scene format but not create it scene status once a scene has been uploaded, it might be preprocessed before being made available in the platform during this process, the status property of a scene can be used to keep track of progress status description indexed scene has been created with cloud resources and has been validated but no data has left your cloud the scene will remain here until someone makes it available through ui or api pending scene has been validated but the server is waiting for the associated resources to be uploaded processing associated data has been uploaded and is currently being processed by the kognic platform, potentially performing conversion of file formats created scene is created and available in the platform failed conversion of scene failed more information can be found in the associated error message invalidated scene was invalidated since it did not load invalidated scene was invalidated due to being uploaded several times invalidated scene was invalidated because it was incorrectly created creating inputs from scene once a scene has been created, it can be used to create inputs which is done by associating it with a project and an input batch consider the following project setup organization # root for projects and scenes └── projects ├── project a ├── batch 1 completed ├── batch 2 open ├── request 1 ├── input 9c08f7a3 3216 4bd6 a41a 1dda6f66f53e – using scene 0edb ├── input ddf548e3 9806 433c afb5 fb951a721462 using scene 37d9 └── └── request 2 └── batch 3 pending └── project b ├── batch 1 └── └── scenes ├── scene 0edb8f59 a8ea 4c9b aebb a3caaa6f2ba3 ├── scene 37d9dda4 3a29 4fcb 8a71 6bf16d5a9c36 └── the create from scene method is used to create inputs from a scene the method takes the scene uuid as input along with annotation information such as project, batch and annotation types for example, to create inputs in project a and batch 2 , you would do the following client cameras create from scene( scene uuid="0edb8f59 a8ea 4c9b aebb a3caaa6f2ba3", project="project a", # important this is the external id and not the title batch="batch 2" # important this is the external id and not the title ) the above code will create inputs for the scene in all requests in batch batch 2 for project project a if the batch parameter is omitted, the latest open batch for the project will be used you can later reuse the same scene to create inputs for other projects and batches creating inputs directly it is often useful to create inputs directly instead of the 2 step process described above to do this, you can simply pass the annotation information directly into the create method of the corresponding scene type for example, to create an input in project a and batch 2 , you would do the following client cameras sequence create( , project="project a", # important this is the external id and not the title batch="batch 2" # important this is the external id and not the title ) this would trigger the scene creation process, and once the scene is created, inputs are created in all requests in the given batch if the batch parameter is omitted, the latest open batch for the project will be used we also provide a wrapper function create inputs to help with this process, see /#creating multiple inputs with one call list scenes note this feature is new in version 1 6 0 it can be useful to list scenes that have been uploaded to the kognic platform one example is to check the status during scene creation scenes can be retrieved in the following way scene uuids = \["cca60a67 cb68 4645 8bae 00c6e6415555", "cc8776d0 f537 4094 8b11 8c2111741e2f"] client scene get scenes by uuids(scene uuids=scene uuids) response the response is a list of scene objects containing the following properties property description uuid uuid used to identify the scene within the kognic platform external id external id supplied during scene creation scene type type of scene (see docid 14dcxcasr7o nam1xyu5z ) status scene status (see /#scene status ) created when the scene was created calibration id calibration used for the scene (if any) view link a url to view the scene in the kognic platform error message if there is an error during scene creation the error message will be included, otherwise it's none list inputs note this feature is new in version 1 7 0 inputs can be queried from the platform using the query inputs method, which can be used in the following way scene uuids = \["cca60a67 cb68 4645 8bae 00c6e6415555", "cc8776d0 f537 4094 8b11 8c2111741e2f"] client scene get scenes by uuids(scene uuids=scene uuids) additional filter parameters for querying inputs are listed below parameter description project project identifier to filter by batch which batch in the project to return inputs for scene uuids return inputs using scenes matching the supplied uuids external ids return inputs using scenes matching the supplied external ids response the response is a list of input objects containing the following properties property description uuid id used to identify the input within the kognic platform scene uuid id used to identify the scene that the input is using request uid id used to identify the request that the input belongs to view link a url to view the input in the kognic platform invalidate scenes note this feature is new in version 1 6 0 if issues are detected upstream related to scenes created, it is possible to invalidate them this could be useful during development or if issues are detected with the data invalidating a scene means that it will be removed from requests, meaning that all inputs using the scene will be deleted in turn invalidated scenes will not produce annotations and any completed annotations of the scene will be removed there is no way to undo this operation so use with caution from kognic io model scene invalidated reason import sceneinvalidatedreason scene uuids = \["0edb8f59 a8ea 4c9b aebb a3caaa6f2ba3", "37d9dda4 3a29 4fcb 8a71 6bf16d5a9c36"] reason = sceneinvalidatedreason bad content client scene invalidate scenes(scene uuids, reason) the following reasons are available when invalidating scenes reason description bad content scene does not load, or has erroneous metadata such as invalid calibration duplicate if the same scene has been created several times incorrectly created if the scene was unintentionally created deleting inputs note this feature is new in version 1 6 0 if issues are detected upstream related to inputs created, it is possible to delete them this could be useful when the issues are related to the input itself and not the scene one example would be if there are two inputs for a lidars and cameras scene, one where we want to annotate in 2d/3d and one where we only want to annotate in 2d if the issue is an erroneous calibration the 2d input can still be used while the 2d/3d input should be deleted deleting an input means that no annotations will be produced for it and any completed annotations of the input will be removed there is no way to undo this operation so use with caution input uuid = "9c08f7a3 3216 4bd6 a41a 1dda6f66f53e" client input delete input(input uuid) creating multiple inputs with one call note this feature is new in version 1 1 9 since the input creation process is asynchronous, it is sometimes useful to wait for the inputs to be created before continuing in order to do this, we provide a wrapper function create inputs which can create multiple scenes and inputs, wait for them to be created (or failed) and yield the results the function will block until it has a result to yield or all of the inputs have completed in one way or another the function takes a list of scenewithpreannotation (a new wrapper object containing a scene and optionally a pre annotation) along with the normal input creation parameters from kognic io tools input creation import create inputs, scenewithpreannotation, inputcreationstatus from kognic io model scene import lidarsandcamerassequence from kognic openlabel models import openlabelannotation scenes with pre annotations list\[scenewithpreannotation] = \[ scenewithpreannotation( scene=lidarsandcamerassequence( ), preannotation=openlabelannotation( ) # optional ), ] for input result in create inputs(client, scenes with pre annotations, "project identifier", batch="batch identifier") \# do something with the result if input result status == inputcreationstatus created print(f"input {input result external id} was created, got uuid {input result input uuid}") elif input result status == inputcreationstatus failed print(f"input {input result external id} failed to be created at stage {input result error stage} with error {input result error message}") else print(f"input {input result external id} is in status {input result status}") note that the functions also accepts the parameters wait timeout and sleep time which can be used to control the wait behavior the wait timeout parameter specifies the maximum time to wait for the inputs to be created/failed, while sleep time specifies the time to sleep between each check units are in seconds the time it takes for inputs to be created depends on their size and the number of inputs to be created so the wait timeout should be set accordingly the default value is 30 minutes, starting from the time when all scene jobs have been committed waiting for scene creation it can sometimes be useful to wait for a scene to be created before continuing this can be done by using below example in utils py import time from kognic io client import kognicioclient from kognic io model import scenestatus def wait for scene job(client kognicioclient, scene uuid str, timeout=20) > scenestatus start time = time time() while (time time() start time) < timeout response = client scene get scenes by uuids(scene uuids=\[scene uuid]) scene = response\[0] if scene status in \[scenestatus created, scenestatus failed] return scene status time sleep(1) raise exception(f"job was not finished {scene uuid}")