Differences

This shows you the differences between two versions of the page.

--- working_with_annotations [2022/03/08 13:39] – [Annotation types] antreas
+++ working_with_annotations [2025/12/23 14:51] (current) – angelos
@@ Line 1: / Line 1: @@
 ===== Working with annotations =====
-==== Annotation types ====
+PMA.core supports three types of annotations: PMA.core annotations, native annotations, and 3rd party annotations.
-PMA.core supports two main types of annotations **PMA.core annotations** and **3rd party annotations** but also some native annotations for the //3dHistech MRXS// and //Hamamatsu NDPI// formats.
+^ Annotation type ^ Origin ^ Format ^ Read/Write ^
+| Pathomation | PMA.studio; SDK | [[https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry|WKT]] | Read / Write |
+| Native | Vendor-specific viewer; Pannoramic viewer; ImageScope | Embedded in the vendor file format | Read-only |
+| Third-party | Indica Labs HALO; Definiens; Visiopharm | .Annotation XML; .XML; .MLD (binary) | Read-only |
+| Third-party | QuPath | .geojson | Read / Write |
+| Third-party | - | .CSV | Write |
+==== Internal storage ====
+PMA.core uses its own internal format with the following structure:
+  * Geometry: based on WKT ([[https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry|Well-known text]]). Supports the following shapes //Polygon, Linestring, Point and Multipoint//
+  * Color: the outline color in [[https://www.w3schools.com/html/html_colors.asp|html format]]
+  * Fill Color: the fill color(if any), only valid for closed shapes like polygon
+  * Classification: A text specifying the classification of an annotation like tumor, necrosis etc.
+  * Notes: Free text notes and additional information you want to store for every annotation
+PMA.core supports 3rd party annotations from the following vendors **Visiopharm**, **Indica Labs** and **Aperio**. Each of these formats is supported via parsing the respective vendor specific file:
+  * Visiopharm //.mld//
+  * Indica Labs //.annotations//
+  * Aperio //.xml//
-PMA.core annotations uses it's own internal format based on WKT(Well-known text) and it supports the following shapes Polygon, Linestring, Point and Multipoint. You can also change the color, fill color and line thickness for these annotations. PMA.core also supports some associated information for every annotation like the classification and free text notes.
-rd party annotations supported are from the vendors **Visiopharm**, **Indica Labs** and **Aperio**. Each of this format is supported via parsing the respective vendor specific file, for Visiopharm that is //.mld//, for Indica Labs is //.annotations// and for Aperio is //.xml//
 ==== Creating and saving ====
-== PMA.core annotations ==
-For reading the PMA.core annotations for a slide you can use the API call [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.GetAnnotations|GetAnnotations]], that returns all PMA.core annotation in json format.
+=== PMA.core annotations ===
-All other PMA.core annotations functionality is provided via the [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.SaveAnnotations|SaveAnnotations]] API call. This call can create new, update and delete many annotations in one API call. PMA.core also provided the functionality to get the length and/or the surface area for already saved annotations via the [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.GetAnnotationDistance|GetAnnotationDistance]] and [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.GetAnnotationSurfaceArea|GetAnnotationSurfaceArea]] API calls.
+For reading the PMA.core annotations for a slide you can use the API call [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.GetAnnotations|GetAnnotations]], that returns all PMA.core annotations in json format.
-== 3rd Party annotations ==
+All other PMA.core annotation functionality is provided via the [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.SaveAnnotations|SaveAnnotations]] API call. This call can create new, update and delete many annotations in one API call. PMA.core also provides the functionality to get the length and/or the surface area for already saved annotations via the [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.GetAnnotationDistance|GetAnnotationDistance]] and [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.GetAnnotationSurfaceArea|GetAnnotationSurfaceArea]] API calls.
-PMA.core can leverage the use of 3rd party annotations via the External Files interface and the appropriate API calls.
+=== 3rd Party annotations ===
-This calls associates a number of files containing any known 3rd party annotations with a slide (for known formats and extensions see the previous paragraph). To associate external files with a slide you have to use the API call [[https://docs.pathomation.com/pma.core.api/#/Api/Slide_SetExternalAnnotationFiles|SetExternalAnnotationFiles]]. This takes an array of tuples containing the //Name// and //Path// for each associated 3rd party annotations file. For //Name// you can use any text to differentiate from other annotations an the //Path// needs to be a //virtual path// to the file containing the annotations.
-You can get the previously set external annotations files for a slide via the [[https://docs.pathomation.com/pma.core.api/#/Api/Slide_GetExternalAnnotationFiles|GetExternalAnnotationFiles]] API call, which returns the array of //Name/Path////Italic Text// tuples for each file associated with any slide
+PMA.core can access 3rd party annotations via the External Files interface and the associated API calls.
+This API associates a number of files containing any known 3rd party annotations with a slide (see previous paragraph). To associate external files with a slide you have to use the API call [[https://docs.pathomation.com/pma.core.api/#/Api/Slide_SetExternalAnnotationFiles|SetExternalAnnotationFiles]]. This takes an array of tuples containing the //Name// and //Path// for each associated 3rd party annotation file. For //Name// you can use any text to differentiate from other annotations an the //Path// needs to be a //virtual path// to the file containing the annotations.
+You can get the previously set external annotations files for a slide via the [[https://docs.pathomation.com/pma.core.api/#/Api/Slide_GetExternalAnnotationFiles|GetExternalAnnotationFiles]] API call, which returns the array of //Name/Path// tuples for each file associated with any slide
 ==== Exporting and format conversion ====
-PMA.core provides a very powerful API to export and convert all known annotations formats to each other, either it is a PMA.core annotations, 3rd party annotation or native annotations. The API call [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.ExportAnnotations|ExportAnnotations]] can convert any known source of annotations,
+PMA.core provides a very powerful API to export and convert all known annotations formats to each other, whether they are PMA.core, 3rd party or native annotations. The API call [[https://docs.pathomation.com/pma.core.api/#/Api/PMA.Services.Api.HistoScope.ExportAnnotations|ExportAnnotations]] can convert any compatible source of annotations
-//PMA.core annotations, Native annotations , Visiopharm , IndicaLabs , Aperio//, to each of the 3rd party formats, Visiopharm  IndicaLabs Aperio, but also two more usefull formats for use outside of PMA.core i.e. the CSV and WKT(Well-Known text) formats. PMA.core will try to convert each format as flawlessly as possible but some shapes in each format are compatible to each other. If the source and destination formats are the same PMA.core will not perform any conversion and will output the original file.
+(//PMA.core annotations, Native annotations , Visiopharm , Indica Labs , Aperio//) to any of the 3rd party formats (Visiopharm, Indica Labs & Aperio). This call also supports two more very useful formats for use outside of PMA.core i.e. the CSV and WKT (Well-Known text) formats. PMA.core will try to convert each format as flawlessly as possible but some shapes are not reproducible as shapes in other formats. If the source and destination formats are the same, PMA.core will not perform any conversion & will output the original file.
+==== More background ====
+Did you know that PMA.core is actually a great tool to integrate different annotations originating for different sources? For more background, have a look at the [[pmann|Pathomation ANNotation subset of functionality]] in the API.
+We have [[https://realdata.pathomation.com/annotations-et-al/|a blog article on annotations and how to handle them]], not just within PMA.core, but throughout [[https://www.pathomation.com/platform|the entire Pathomation software platform]].