This project has multiple goals.<\/p>\n
The short term goal is to provide ExtendScript access to Illustrator data that is currently inaccessible to ExtendScript scripts.<\/p>\n
There is a discrepancy between what can be accessed using the C++ API and what can be accessed from ExtendScript.<\/p>\n
This plug-in attempts to bridge that gap.<\/p>\n
The plug-in currently provides an additional DOM (Document Object Model), unrelated to the ExtendScript DOM.<\/p>\n
The AIntrospector DOM is more low-level than the ExtendScript DOM.<\/p>\n
This alternative DOM can be used from ExtendScript alongside the ExtendScript DOM and offers access to areas that are inaccessible to the ExtendScript DOM.<\/p>\n
At this time, the AIntrospector DOM is still very sparse: it is populated with new attributes and new features on an ‘as-needed’ basis for some real-life projects. For example, the AIntrospector DOM gives you access to information about ‘type on a path’ that is not available in the ExtendScript DOM (nor in the C++ API).<\/p>\n
The current focal areas, where the DOM is being extended, are determined by the needs of current customers who have a solid commitment to licensing AIntrospector.<\/p>\n
The low-level AIntrospector DOM can be accessed from CEP\/JavaScript as well as from ExtendScript.<\/p>\n
When accessing the DOM from CEP\/JavaScript, there is no ‘intermediate’ use of ExtendScript: JavaScript calls are handled by the plug-in without any use of ExtendScript. This allows the creation of CEP panels that are totally free of any ExtendScript.<\/p>\n
The hope\/assumption is that this can put an end to PARM\/MRAP errors which seem to be caused by some ‘disconnect’ between the ExtendScript engine and Illustrator.<\/p>\n
When PARM\/MRAP happens, Illustrator remains fully responsive and alive to the user, and at the same time, ExtendScript scripts can still be run, but somehow, ExtendScript seems to lose its grip on Illustrator, and anything you try causes a PARM\/MRAP error, which can only be cured by restarting Illustrator.<\/p>\n
One of the underlying principles is to support asynchronous access. The idea is that there are two realms: one ‘inside’ Illustrator, and one ‘outside’ Illustrator.<\/p>\n
The AIntrospector API bridges these two realms.<\/p>\n
When calling from ‘outside’ to ‘inside’ there is a substantial cost in time and performance, especially when calling from JavaScript\/CEP: we’re switching between two very different contexts.<\/p>\n
The AIntrospector DOM is being designed to reduce the number of such context switches as much as possible.<\/p>\n
The ‘outside’ code can prepare a request object, which is a bit like a shopping list or ‘to do’ list.<\/p>\n
The request object can express complex queries into the Illustrator data structures, and the idea is to shoehorn as much as possible into a single request.<\/p>\n
The request is then fired off, the context switches, and the ‘inside’ resolves and execute the request, without needing to call back to the outside during processing.<\/p>\n
If you have choice between formulating three small requests, or instead an equivalent single complex requests, you would choose the latter because you will only ‘pay’ for one context switch between ‘outside’ and ‘inside’.<\/p>\n
Once the low-level DOM nears completion, the mid term goal is to attempt to build a second, higher level DOM on top of the low-level AIntrospector DOM. This new DOM would be as close to the ExtendScript DOM as possible, and I would try and make the asynchronicity as invisible as possible, so existing ExtendScript scripts might be able to run in a JavaScript\/CEP environment (as opposed to the ExtendScript engine) against the new DOM.<\/p>\n
Another aspect of the plug-in is to provide ‘GPU-like’ features. Some tasks are too massive to be handled in ExtendScript or JavaScript, but are feasible in C++. The plug-in will gradually provide functions to handle such requests. I’ve added one already as a proof of concept: simplifyPath.<\/p>\n
Gradually, the focus will shift from ExtendScript to providing more features to CEP\/JavaScript.<\/p>\n
The API provided by the AIntrospectorUI extension works both in ExtendScript and in JavaScript.<\/p>\n
From JavaScript, all calls into AIntrospector are asynchronous.<\/p>\n
From ExtendScript, calls can be either synchronous or asynchronous.<\/p>\n
Make sure to start the script with something like<\/p>\n
#include \"<some path>\/standalone.jsx\" \n<\/code><\/pre>\nor equivalent.<\/p>\n
This loads and initializes the ExtendScript infrastructure.<\/p>\n
XUID<\/h2>\n
In order to reference objects in Illustrator (page items, colors, documents, artboards…) the plug-in uses XUID (eXtended UID).<\/p>\n
For many object types, XUID are just plain GUID.<\/p>\n
But some objects in Illustrator do not have the internal data structures to retain their GUID. There is no way for Illustrator to ‘remember’ what the GUID for those objects would be.<\/p>\n
In order to handle such objects (e.g. Artboards), the plug-in uses the GUID of the ‘owner’ of the object, suffixed with a short string. Part of this string will be a four-letter code:<\/p>\n
ArBd -> Artboard\nArSt -> Art Style\nLiEf -> Live Effect\nLayr -> Layer\n<\/code><\/pre>\nArtboards<\/h3>\n
For example, if a document has GUID 706c0a02-32fd-4fae-b745-778ba6995328, then its artboards will have the following XUID:<\/p>\n
706c0a02-32fd-4fae-b745-778ba6995328ArBd0\n706c0a02-32fd-4fae-b745-778ba6995328ArBd1\n706c0a02-32fd-4fae-b745-778ba6995328ArBd2\n... and so on\n<\/code><\/pre>\nFor artboards, the owner (document) GUID is suffixed with a type code (ArBd = Artboard) and an index 0..n-1 where n = number of artboards.<\/p>\n
By nature, artboards do not have ‘stable’ XUID: if the order of the artboards in a document changes, the XUID associated with any of the artboards will change.<\/p>\n
Layers<\/h3>\n
Any group in an Illustrator document will have its own GUID.<\/p>\n
Illustrator layers are always associated with a special group (a layer group), and becaused of that, they don’t have their own GUID.<\/p>\n
Instead they have an XUID which is derived from the GUID of the underlying layer group.<\/p>\n
So, if we have a layer ‘ABC’, and the associated layer group has a GUID of<\/p>\n
1715b7bb-0b79-486f-9cbd-c56846e73400\n<\/code><\/pre>\nthen the layer will have XUID<\/p>\n
1715b7bb-0b79-486f-9cbd-c56846e73400Layr\n<\/code><\/pre>\nLive Effects<\/h3>\n
Live effects are owned by the application, not by a document.<\/p>\n
The Illustrator application has a fixed GUID 21862fc3-f16b-42b6-acb3-00165cedd121, and the live effects have an XUID based on their name derived from that.<\/p>\n
21862fc3-f16b-42b6-acb3-00165cedd121LiEfLive Effect Name\n<\/code><\/pre>\nArt Styles<\/h3>\n
Art styles are owned by a document.<\/p>\n
Art styles have an XUID based on their name derived from the document GUID.<\/p>\n
1715b7bb-0b79-486f-9cbd-c56846e73400ArStArt Style Name\n<\/code><\/pre>\nSynchronous vs Asynchronous<\/h2>\n
Asynchronous use of the API is compatible with both JavaScript and ExtendScript.<\/p>\n
Asynchronous API call:<\/h3>\nAIn.sendAIntrospectorQuery(query, function(result) {...});\n<\/code><\/pre>\nSynchronous API call (ExtendScript only):<\/h3>\nresult = AIn.sendAIntrospectorQuery(query);\n<\/code><\/pre>\nSynchronous call with ‘implicit reference’ (ExtendScript only):<\/h3>\n
In ExtendScript you can omit the reference attribute from a query object and instead use<\/p>\n
result = AIn.sendPageItemIntrospectorQuery(pageItem, query);\n<\/code><\/pre>\nThis allows you to reference objects directly, rather than via the reference mechanism.<\/p>\n
Symbolic constants<\/h2>\n
A lot of Illustrator calls in the C++ API take enumeration constants.<\/p>\n
These are numerical (integer) constants that each represent a particular state or condition.<\/p>\n
For example, in the C++ API, you’ll find<\/p>\n
\/** Type constants for drawing modes. *\/\n enum AIDrawingMode\n {\n kAIDrawNormalMode = 0,\n kAIDrawBehindMode,\n kAIDrawInsideMode\n };\n<\/code><\/pre>\nTo keep things readable in C++ code, developers will rather use ‘kAIDrawNormalMode’ instead of a ‘0’. These two things are equivalent as far as the C++ compiler is concerned, but writing kAIDrawNormalMode makes it much easier to understand the code for the human reader of the C++ code.<\/p>\n
The AIntrospector plug-in uses a similar mechanism, and will allow symbolic strings for nearly all parameters for API calls that need such integer values.<\/p>\n
Any call to AIntrospector that has a JSON construct with a drawing mode parameter will accept either an integer value, as well as a string value.<\/p>\n
You can either use<\/p>\n
{\n ...\n drawingMode: 1\n ...\n }\n<\/code><\/pre>\nor<\/p>\n
{\n ...\n drawingMode: \"kAIDrawBehindMode\"\n ...\n }\n<\/code><\/pre>\nand both will work the same.<\/p>\n
It will also return these symbolic strings rather than the ‘naked’ integer values, so the returned data from a ‘getinfo’ becomes is easier to understand.<\/p>\n
Example:<\/p>\n
{\n \"uid\": \"460cec74-8915-477b-8baa-bc527d0cc094\",\n \"name\": \"my group\",\n \"type\": \"art\",\n \"artType\": \"kTextFrameArt\",\n \"artBounds:top\": \"-293.2734375\",\n \"filePath\": \"\",\n \"pathObject\": \"3c336f5b-ccf4-4d20-9f6a-389a3af3d30f\",\n \"typeOnPath\": {\n \"typeOnPathEffect\": \"kTypeOnPathRainbow\",\n \"typeOnPathFlipped\": \"1\"\n }\n }\n<\/code><\/pre>\nartType is returned as ‘kTextFrameArt’, which is equivalent with the integer constant ’12’. Seeing ‘kTextFrameArt’ is a lot easier to understand than seeing ’12’.<\/p>\n
Reference<\/h2>\n
To refer to an object in Illustrator you can use a reference object.<\/p>\n
There are four types of references: symbolic, uid, indexed and relative<\/p>\n
A single reference object can refer to multiple Illustrator objects (e.g. referring to the current selection)<\/p>\n
Symbolic<\/h3>\n
To refer to the current document:<\/p>\n
{\n type: \"symbolic\",\n symbolType: \"curDoc\"\n }\n<\/code><\/pre>\nTo refer to the current selection (which might refer to multiple elements):<\/p>\n
{\n type: \"symbolic\",\n symbolType: \"selected\"\n }\n<\/code><\/pre>\nTo refer to the application object (this should always return the pre-determined GUID AIn.C.APPLICATION_UID = “21862fc3-f16b-42b6-acb3-00165cedd121”):<\/p>\n
{\n type: \"symbolic\",\n symbolType: \"application\"\n }\n<\/code><\/pre>\nuid<\/h3>\n
To refer to an object by its XUID:<\/p>\n
{\n type: \"uid\",\n uid: \"706c0a02-32fd-4fae-b745-778ba6995328\"\n}\n<\/code><\/pre>\nindexed<\/h3>\n
This is a recursive definition: you need a nested reference object to use the index with.<\/p>\n
To refer to an object ‘below’ another object by its index:<\/p>\n
{\n type: \"indexed\",\n index: anIdx,\n reference: {\n ... a reference object for the parent object ...\n }\n }\n<\/code><\/pre>\nrelative<\/h3>\n
This is a recursive definition. you need a nested reference object as the base for the relation.<\/p>\n
The available relations are:<\/p>\n
ancestor\nchild\ndescendant\nnext\nparent\nprevious\n<\/code><\/pre>\nancestor = recursive parent descendant = recursive child<\/p>\n
The ancestor and descendant references track down via parent or child relations.<\/p>\n
To refer to an object relative to another object:<\/p>\n
{\n type: \"relative\",\n relation: \"parent\",\n reference: {\n ... a reference object for the child object ...\n }\n }\n\n\n {\n type: \"relative\",\n relation: \"child\",\n reference: {\n ... a reference object for the parent object ...\n }\n }\n\n\n {\n type: \"relative\",\n relation: \"next\",\n reference: {\n ... a reference object for the sibling object ...\n }\n }\n\n\n {\n type: \"relative\",\n relation: \"previous\",\n reference: {\n ... a reference object for the sibling object ...\n }\n }\n\n\n {\n type: \"relative\",\n relation: \"ancestor\",\n includeRoots: true\/false, \/\/ optional, default = false\n reference: {\n ... a reference object for the descendant object ..\n },\n filter: ... a filter ...,\n visitFilter: ... a filter ...\n }\n\n\n {\n type: \"relative\",\n relation: \"descendant\",\n includeRoots: true\/false, \/\/ optional, default = false\n reference: {\n ... a reference object for the ancestor object ...\n },\n filter: ... a filter ...,\n visitFilter: ... a filter ...\n }\n<\/code><\/pre>\nfilter<\/h4>\n
The filter determines which elements are to be selected by the reference<\/p>\n
visitFilter<\/h4>\n
The visitFilter determines how to recurse up or down: if an element does not match the visitFilter the recursion will not descend or ascend into it.<\/p>\n
includeRoots<\/h4>\n
If includeRoots is true, then the referenced object(s) themselves are also tested for matching against the filter and can be included in the result.<\/p>\n
By default only objects ‘one step removed’ – i.e. children or parents – of the referenced object(s) are tested.<\/p>\n
filter objects<\/h4>\n
A basic filter object will compares attribute values:<\/p>\n
{\n attr1: value1,\n attr2: value2...\n }\n<\/code><\/pre>\nThis will filter all elements that have attr1 == value1 and attr2 == value2.<\/p>\n
Example:<\/p>\n
{\n isArtClipping: \"1\"\n }\n<\/code><\/pre>\nwill filter all elements that have isArtClipping = 1.<\/p>\n
To change the filter comparison operation from ‘equals’ to something else (<, <=, >, >=), you need to nest the filter into a ‘cmp’ object.<\/p>\n
{\n cmp: \"<\",\n filter : {\n ... a basic filter object ...\n }\n }\n<\/code><\/pre>\nThis causes the comparison to compare ‘attr < value’ instead of ‘attr == value’.<\/p>\n
Example:<\/p>\n
{\n cmp: \"<=\",\n filter : {\n artType: \"kCompoundPathArt\"\n }\n }\n<\/code><\/pre>\nwill filter all art elements that have an art type <= kCompoundPathArt. kCompoundPathArt is a symbolic representation of the integer value 3.<\/p>\n
Filters can be inverted or combined.<\/p>\n
To invert a filter:<\/p>\n
{\n invert: true\n filter : {\n ... a filter object ...\n }\n }\n<\/code><\/pre>\nTo combine two or more filters with ‘and’:<\/p>\n
{\n and: \n [\n {\n ... filter object 1 ...\n },\n {\n ... filter object 2 ...\n }\n ...\n ]\n }\n<\/code><\/pre>\nTo combine two or more filters with ‘or’:<\/p>\n
{\n or: \n [\n {\n ... filter object 1 ...\n },\n {\n ... filter object 2 ...\n }\n ...\n ]\n }\n<\/code><\/pre>\nComplex references<\/h3>\n
It is allowed to have multiple nested reference objects.<\/p>\n
For example, this works:<\/p>\n
{\n opcode: \"getinfo\", \n attr: [ \"uid\", \"name\" ],\n reference: {\n type: \"relative\", \n relation: \"child\",\n reference: {\n type: \"relative\", \n relation: \"child\",\n reference: {\n type: \"uid\", \n uid: AIn.C.APPLICATION_UID\n }\n }\n }\n }\n<\/code><\/pre>\nIt will retrieve all the children (e.g. layers, art styles) for all open documents: documents are children of the application, and layers and art styles are children of the documents.<\/p>\n
Request<\/h2>\n
Requests allow us to ‘do’ something (i.e. extract data, or make changes to the document).<\/p>\n
Asynchronous calls will always need to use a request that contains a reference object, so the plug-in can know what objects to target with the request.<\/p>\n
Synchronous call with ‘implicit reference’ can omit the reference object from the request. They target the object that is provided in the synchronous call.<\/p>\n
Each request needs at least an opcode (OPeration CODE).<\/p>\n
The following opcodes are currently supported (work in progress):<\/p>\n
disposeArt\ngetinfo\nnewArt\nreorderArt\nselect\nsetinfo\nsimplifyPath\n<\/code><\/pre>\ndisposeArt<\/h3>\n {\n opcode: \"disposeArt\",\n reference: {\n .... a reference object ...\n }\n }\n<\/code><\/pre>\nThis will remove the referenced art from the document.<\/p>\n
getinfo<\/h3>\n
This request retrieves information about one or more objects and returns it.<\/p>\n
{\n opcode: \"getinfo\",\n alwaysReturnArray: true\/false, \/\/ optional, defaults to false\n attr: ... a single attr or an array of attr ...\n reference: {\n .... a reference object ...\n }\n }\n<\/code><\/pre>\nWhen alwaysReturnArray is true, the returned value is always an array (which could be empty or have only a single element).<\/p>\n
If alwaysReturnArray is false the returned value is either a single item if there is only a single result, or an array if there are multiple results.<\/p>\n
There is some support for function-like calls. Instead of just an attribute name, they are specified by 2-element arrays [ <<attr>>, <<param>> ]<\/code><\/p>\nSupported function-like attr:<\/p>\n
attr = allArt, param = { artType: ..., whichAttr:..., matchAttr:...}\n each of those either a symbolic string, \n e.g. 'kArtSelected' or an integer\n attr = artOrder, param = string with artUID to compare with\n attr = artUserAttr, param = whichAttr (either a symbolic string, \n e.g. 'kArtSelected' or an integer)\n attr = pathSegments, param = { segNum: ..., segCount: .... }. \n pathSegments can also be used as a normal attribute\n attr = pathLength, param = AIReal flatness\n attr = validArt, param = bool searchAllLayerLists\n<\/code><\/pre>\nTo call these, you need to provide a two-element array: first element is the attr name, second element is a JSON-encoded parameter construct.<\/p>\n
attr can currently be one or more selected from (work in progress):<\/p>\n
artBounds\n artBoundsOptions\n artDrawingMode\n artHasFill\n artHasStroke\n artIsGraph\n artStrokeParams\n artStyle\n artStyleName\n artStyleScaleFactor\n artSubType\n artTargettingAction\n artTimeStampOptions\n artTransferAttrsOptions\n artType\n artXMP\n ascent\n autoKernType\n autoLeading\n baseLineShift\n characterRotation\n childCount\n contents\n descent\n dictionary\n distanceToBaseLine\n entryType\n extractedText\n filePath\n font\n fontBaselineOption\n fontCapsOption\n fontSize\n frameIndex\n glyphOrientation\n hasNote\n horizontalScale\n isArtClipping\n isArtStyledArt\n isEnvelope\n layerGroup\n leading\n lineOrientation\n matrix\n maxCapHeight\n minCapHeight\n name\n next\n note\n onPathTextTRange\n origins\n paintOrder\n parent\n parsedStyle\n partOfLinkedText\n pathArea\n pathClosed\n pathGuide\n pathHasLength\n pathIsClip\n pathObject\n pathPolarity\n pathSegmentCount\n pathSegments (can also be used as a function)\n placedType\n pointTextAnchor\n prepArt\n previous\n spaceGlyphWidth\n storyIndex\n styledArt\n text\n textAntialias\n textFrameColumnCount\n textFrameColumnGutter\n textFrameMatrix\n textFrameOpticalAlignment\n textFrameRowCount\n textFrameRowGutter\n textFrameRowMajorOrder\n textFrameSpacing\n textFrameStoryDirection\n textFrameType\n textOrientation\n tracking\n type\n typeOnPath\n typeOnPathEffect\n typeOnPathFlipped\n uid\n underlinePosition\n underlineThickness\n verticalScale\n<\/code><\/pre>\nNot all attributes make sense for all object types. If the attribute is not defined, an empty string will be returned.<\/p>\n
If the reference resolves to multiple objects, an array of replies will be returned.<\/p>\n
The reply object will contain an entry for each requested attr.<\/p>\n
Example:<\/h4>\n {\n opcode: \"getinfo\",\n attr: \"uid\"\n reference: {\n type: \"symbolic\",\n symbolType: \"root\"\n }\n }\n<\/code><\/pre>\nwill return a single object<\/p>\n
{\n uid: \"706c0a02-32fd-4fae-b745-778ba6995328\"\n }\n<\/code><\/pre>\nsingle uid, the uid of the document.<\/p>\n
Example:<\/h4>\n {\n opcode: \"getinfo\",\n attr: \"name\"\n reference: {\n type: \"uid\",\n uid: [\"706c0a02-32fd-4fae-b745-778ba6995328\", \n \"807c0a02-32fd-4fae-b745-778ba6995439\"]\n }\n }\n<\/code><\/pre>\nwill return an array of two objects, the names of these objects:<\/p>\n
[\n {\n name: \"name 1\"\n },\n {\n name: \"name 2\"\n }\n ]\n<\/code><\/pre>\nExample:<\/h4>\n {\n opcode: \"getinfo\",\n attr: [ \"name\", \"childCount\" ]\n reference: {\n type: \"uid\",\n uid: [\"706c0a02-32fd-4fae-b745-778ba6995328\", \n \"807c0a02-32fd-4fae-b745-778ba6995439\"]\n }\n }\n<\/code><\/pre>\nwill return an array of two objects:<\/p>\n
[\n {\n name: \"name 1\",\n childCount: 5\n },\n {\n name: \"name 2\"\n childCount: 0\n }\n ]\n<\/code><\/pre>\nExample:<\/h4>\n {\n opcode: \"getinfo\",\n attr: [ \"allArt\", { \"artType\" : \"kAnyArt\" } ],\n reference: {\n .... a reference to a document ...\n }\n }\n<\/code><\/pre>\nwill call allArt({ “artType” : “kAnyArt” }) and return all UIDS of all art in the referenced document.<\/p>\n
newArt<\/h3>\n {\n opcode: \"newArt\",\n params: {\n artType: ... art type...,\n paintOrder: ... paint order...,\n prepArt: ... a reference to a preparatory art object ...\n }\n }\n<\/code><\/pre>\nThis will create a new, empty art object.<\/p>\n
It will execute the C++ AIArtSuite call:<\/p>\n
AIAPI AIErr(*NewArt)(ai::int16 type, ai::int16 paintOrder, \n AIArtHandle prep, AIArtHandle *newArt)\n<\/code><\/pre>\nreorderArt<\/h3>\n {\n opcode: \"reorderArt\",\n reference: {\n ... an art object...\n }\n params: {\n paintOrder: ... paint order...,\n prepArt: ... a reference to a preparatory art object ...\n }\n }\n<\/code><\/pre>\nThis will reorder the targeted art relative to the prep art.<\/p>\n
It will execute the C++ AIArtSuite call:<\/p>\n
AIAPI AIErr (*ReorderArt) (AIArtHandle thisArt, ai::int16 paintOrder, \n AIArtHandle prep)\n<\/code><\/pre>\nselect<\/h3>\n
Will attempt to select the referenced items<\/p>\n
setinfo<\/h3>\n
This request will change some attributes or related data on the referenced objects.<\/p>\n
simplifyPath<\/h3>\n
Will attempt to simplify the path. Smoothing uses a sliding average of smoothAveragePointCount to average out points along the path as long as they are no more than smoothToleranceInPoints apart.<\/p>\n
If a point between two other points is less than toleranceInPoints away from the other two, it will be removed.<\/p>\n
If a compound path subsegment has less than minSegmentCount segments, it will be deleted<\/p>\n
{\n opcode: \"simplifyPath\",\n smoothToleranceInPoints: 10,\n smoothAveragePointCount: 10,\n toleranceInPoints: 0.4,\n minSegmentCount: 4,\n reference: ...\n }\n<\/code><\/pre>\nThis seems to work well on bitmaps that have been converted to paths and zig-zag all over the place. I’ve been able to reduce a sample compound path from > 200,000 path segments down to a few 10,000 while retaining something visually very close to the original. It also helps in making a path more manageable for manual editing.<\/p>\n","protected":false},"excerpt":{"rendered":"
AIntrospector 1.0.11 – 30 May 2018 This project has multiple goals. Short Term The short term goal is to provide ExtendScript access to Illustrator data that is currently inaccessible to ExtendScript scripts. There is a discrepancy between what can be … Continue reading