Step API - various utility functions for modules and UIs to reference step state

jywarren commented 6 years ago

While working on #214 I realize there are a lot of common needs that one has when writing a module or a UI. Writing a complex interface/module is a great way to discover what extra utility methods we really need to make life easier for module developers.

This relates to #122 -- but comes after it. First, in #122, we should minimize things we require in a module. Then we should make a range of abilities available to modules.

Let's make a list, and we can work to add them as we go -- this is a list of standard values or functions we should make available both to a given module's instantiation as a "step" -- and to the UI that it generates and updates:

Step (priority)

[x] the input image src - as soon as it's first passed in - see implementation in #214's custom UI
[ ] listeners for the above events? (onDraw for the first, onComplete for the second?)
[x] various properties of the above - width, height, size, format, or utilities to calculate them - getWidth(), getHeight() etc
[x] setOptions() and getOptions()
[x] a reference to any given step's generated metadata (like from QRCode module)
[x] a reference to the previous step - getPreviousStep()
[x] a reference to the next step - getNextStep()
[x] getStep(offset) more generically
[x] getStep(offset).input and .output or .getInput() and .getOutput()
[x] a reference to the current step's index -- probably generated, like getIndex()

Step (can do later)

[ ] the output image src - as soon as it's first calculated

Module

the module name & description - module.name?

Environment

inBrowser (done, could be more consistent)
hasWebGl (after #216 this will be important to distinguish simply from a browser)

UI

These ought to be provided by the UI -- I'm focused on HTML right now, but let's ensure the default HTML UI sets a good example:

[ ] unique selector to the "step" element -- in default UI - step.element
[ ] the displayed image preview (in the default UI this is an instance of the actual image) - step.imgElement - believe this exists already but needs documentation
[ ] link to the "details" or "settings" area - although this varies with UI and could be calculated from the step.element selector
[ ] a simple way to output any results or textual outputs of a module into either the HTML or CLI display, like display(message)

Versioning

Once we implement the full Step API, we may want to bump a major version number - x.0.0, update the docs, and tell people not to use the old way of writing modules with the various output steps currently in the docs.

jywarren commented 6 years ago

Made lots of small edits to this - worth looking over, @tech4GT !! Thanks!!

tech4GT commented 6 years ago

@jywarren going through this now😀

tech4GT commented 6 years ago

@jywarren Should we close this one before moving on to meta modules?? since these really are just a set of very small issues considering we have already implemented the major ones, this will increase our milestone progress quite a bit!!

jywarren commented 6 years ago

yes, i agree!

Anything to add here that we've learned is useful?

On Fri, Jun 8, 2018 at 2:24 PM, Varun Gupta notifications@github.com wrote:

@jywarren https://github.com/jywarren Should we close this one before moving on to meta modules?? since these really are just a set of very small issues considering we have already implemented the major ones, this will increase our milestone progress quite a bit!!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/publiclab/image-sequencer/issues/242#issuecomment-395847373, or mute the thread https://github.com/notifications/unsubscribe-auth/AABfJ413Ub4o5Pc2LuGqbkWwnuBrYu05ks5t6sF5gaJpZM4TymSk .

tech4GT commented 6 years ago

@jywarren can you please explain the first and second point in step? what do we exactly mean by having it as soon as its calculated and passed??

jywarren commented 6 years ago

Just that it would be nice to, from inside the step, be able to refer back to the untouched original input image, and, after it's been run once, to the current (or most recent) output (for example to see if our calculated output is different from last time it was run?).

tech4GT commented 6 years ago

@jywarren Oh okay I got it so we can have functions like

function getSource(){
}

but I still don't get the second point, do we want to have the outputs stored in an array, each time the step is run?

jywarren commented 6 years ago

I think the output is less needed. In theory you can ask the next step for its input.

On Mon, Jun 11, 2018 at 10:54 AM Varun Gupta notifications@github.com wrote:

@jywarren https://github.com/jywarren Oh okay I got it so we can have functions like

function getSource(){ }

but I still don't get the second point, do we want to have the outputs stored in an array, each time the step is run?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/publiclab/image-sequencer/issues/242#issuecomment-396272276, or mute the thread https://github.com/notifications/unsubscribe-auth/AABfJ6m5q0inSvV2z47x0Xr9tm38pEi3ks5t7oSLgaJpZM4TymSk .

tech4GT commented 6 years ago

So @jywarren should I not do the second one?

jywarren commented 6 years ago

Yeah, i guess so, at least not for now. This is a kind of "wishlist" so we can identify the most helpful items to implement in our first more formalized Step API.

On Mon, Jun 11, 2018 at 11:15 AM Varun Gupta notifications@github.com wrote:

So @jywarren https://github.com/jywarren should I not do the second one?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/publiclab/image-sequencer/issues/242#issuecomment-396279458, or mute the thread https://github.com/notifications/unsubscribe-auth/AABfJyZ1NjCBFg1Nx2qhadQvDvDbBVmaks5t7ok5gaJpZM4TymSk .

tech4GT commented 6 years ago

Oh i got it!! Actually i was seeing in terms of progress percentage of the core work milestone so we can implement the ones we need right now and then maybe remove this from the core work and keep breaking out separate issues out of this as we need them, what say?

jywarren commented 6 years ago

Great. Yes, let's select the ones we most want.

On Mon, Jun 11, 2018 at 11:31 AM Varun Gupta notifications@github.com wrote:

Oh i got it!! Actually i was seeing in terms of progress percentage of the core work milestone so we can implement the ones we need right now and then maybe remove this from the core work and keep breaking out separate issues out of this as we need them, what say?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/publiclab/image-sequencer/issues/242#issuecomment-396285208, or mute the thread https://github.com/notifications/unsubscribe-auth/AABfJyfd0oygYZ8DeMOM6H0C5NJ_G9beks5t7o0tgaJpZM4TymSk .

tech4GT commented 6 years ago

@jywarren Can you please help me with that? I think we should handle UI later with the rest of the UI improvements so leaves us with step, can you please mark the ones we should do in step?

jywarren commented 6 years ago

I re-ordered them - I agree about the UI ones -- and otherwise i think the output src is really the only one we can leave for later. It won't even be too hard if you can get access to the next step, and it's input.

jywarren commented 6 years ago

UI ones are nice to break out into a separate issue -- all related

jywarren commented 6 years ago

Hi, for the listeners, I guess I am thinking of ways that in the step setup, you could create functions that would run upon specific triggers. We currently do this as part of the UI for some steps, but you could imagine this happening in the step itself for non-UI reasons too, perhaps?

https://github.com/publiclab/image-sequencer/blob/master/src/ui/UserInterface.js

Maybe events for onUpdate for when settings change... can you think of others? And what do you think about these being pulled back from the UI into the main step API, for using outside the UI context? I'm not sure about this, so interested to hear your thoughts!

tech4GT commented 6 years ago

@jywarren yeah this could make sense for when options are updated and when the module is removed maybe, I think we should implement this separate from the UI api, since UI api handles events on sequencer and this new api will handle events on the module itself!!

tech4GT commented 6 years ago

All of core work on this has been done, taking this out of the milestone core work now!!

publiclab / image-sequencer