netnet-standard-library

nn (netnet-standard-library.js) is a browser based JavaScript library designed to aid creative coders (artists, designers, etc), it's a core utility library used within netnet.studio; both in the sense that it can be used to create sketches in netnet, but also that it's used to create netet.studio itself. It can also be used outside of netnet.studio as you would any other typical JavaScript library (with some exceptions, see note below).

There are loads of amazing creative coding libraries out there (p5.js, three.js, tone.js, A-Frame, hydra.js, D3.js, Paper.js, GSAP, etc) which extend the capabilities of the Web's creative APIs and often provide a framework for expressing higher level concepts (the way A-Frame's Entity-Component-System adds game design principles to the WebGL and WebXR APIs or the way Tone.js adds music theory to the WebAudio API). Unlike these libraries, nn doesn't extend or abstract the Web's more creative APIs, instead it has a much more modest goal of expanding on JavaScript's standard library (like it's Math object) as well as some of the Web's core APIs (like window and navigator), in this way that might be useful for artists. It's more of a utility library than it is a creative framework.

This repo consists of a number of git "sub-modules", namely Averigua.js, Maths.js, Color.js and FileUploader.js, all of which can be used independently. This repo simply packages them up in one place, provides thorough documentation and adds a few more properties and methods specifically for aiding beginners embarking on their creative coding journey on netnet.studio.

using the library

CDN

You can use the library by importing it with a <script> linking to a CDN like this:

<script src="https://cdn.jsdelivr.net/gh/netizenorg/netnet-standard-library/build/nn.min.js"></script>

download locally

If you prefer to download a copy locally, you can download the just minified library here and include it in your local project.

Or use npm:

npm install git+https://github.com/netizenorg/netnet-standard-library.git

NPM will of course download much more than you need (the entire project).

You can also use this library directly on netnet.studio by simply including a script tag in your sketch. Check out this example on netnet.studio. NOTE: that will only work in a "sketch", if you are working on a "project" on netnet, make sure to either include a copy of the library in your repo or use the link to the CDN above.

setup

<!-- import the library -->
<script src="https://cdn.jsdelivr.net/gh/netizenorg/netnet-standard-library/build/nn.min.js"></script>
<script>
  /* global nn */

  // a function which uses the library's randomColor()
  // method to change the page's background color
  function changeBGColor () {
    nn.get('body')
      .css({
        background: nn.randomColor()
      })
  }

  // change the background color when the page loads
  nn.on('load', changeBGColor)
  // change background color when the page is clicked
  nn.on('click', changeBGColor)
</script>

examples

For more examples demonstrating how this library can be used checkout the examples doc

API / documentation

properties (internal variables)

• nn.width // browser's current width
• nn.height // browser's current height
• nn.mouseX // mouse's current x position
• nn.mouseY // mouse's current y position
• nn.mouseDown // is mouse pressed or not

methods (internal functions)

• nn.on() // register an event listener on the window
• nn.create() // creates an "overloaded" HTMLElement
• nn.get() // selects an element on the page and returns an "overloaded" one
• nn.getAll() // selects all matching elements and returns"overloaded" ones
• nn.loadImage() // a Promised based approach for loading images
• nn.modifyPixels() // method for processing/filtering images
• nn.askForStream() // ask user permission to use their mic/camera
• nn.askForGPS() // ask user permission for location data
• nn.MIDI() // access any plugged in MIDI devices
• nn.fetch() // a version of fetch() which gets around CORS issues

Function for binding CSS variables to interactions with HTML elements (input, buttons, etc)

• nn.bindCSS() // binds elements to CSS variables

Functions for working with data, specifically designed for JSON or CSV data:

• nn.loadData() // load data from a URL
• nn.parseData() // parse a JSON or CSV string
• nn.stringifyData() // stringify an JSON object or CSV array
• nn.parseCSV() // parse CSV string
• nn.parseJSON() // parse JSON string
• nn.stringifyCSV() // array to CSV string
• nn.stringifyJSON() // array/object to JSON string

Functions for detecting useful information about your visitor's device. These come from the Averigua.js sub-module.

• nn.isMobile() // is the visitor on a mobile device
• nn.hasWebGL() // does their device support 3D graphics
• nn.hasWebVR() // does their device support Virtual Reality
• nn.hasMIDI() // does their device support MIDI
• nn.hasTouch() // does their device have a touch screen
• nn.orientation() // what is the device's orientation
• nn.screen() // info about their screen
• nn.gpuInfo() // info about their graphics card
• nn.browserInfo() // what type of browser are they on
• nn.platformInfo() // info about their computer
• nn.audioSupport() // info about their browser's audio support
• nn.videoSupport() // info about their browser's video support

Other useful math functions often used in creative coding projects which are not included in JavaScript's built in Math object. These come from the Maths.js sub-module.

• nn.norm() // normalize a value
• nn.clamp() // clamp a value to given range
• nn.lerp() // linear interpolation
• nn.map() // map a value from one range to another
• nn.dist() // the distance between two points
• nn.angleBtw() // the angle between two points
• nn.radToDeg() // convert an angle in radians to degrees
• nn.degToRad() // convert an angle in degrees to radians
• nn.cartesianToPolar() // convert cartesian coordinates to polar
• nn.polarToCartesian() // convert polar coordinates to cartesian
• nn.shuffle() // randomize the items in an array
• nn.randomInt() // generate a random integer (whole number)
• nn.randomFloat() // generate a random float (decimal number)
• nn.random() // generate a random number, or select a random item from an array
• nn.perlin() // generate random "perlin" noise
• nn.ease() // a collection of easing/tweening functions

Functions for doing various color maths. These come from the Color.js sub-module.

• nn.randomColor() // generate a random color string
• nn.isLight() // checks if a color is light or dark
• nn.colorMatch() // finds color strings in larger strings
• nn.alpha2hex() // converts alpha float value to hex byte string
• nn.hex2alpha() // converts a hex byte string to alpha float value
• nn.hex2rgb() // converts a hex color string to an rgb object
• nn.hex2hsl() // converts a hex color string to an hsl object
• nn.hex2hsv() // converts a hex color string to an hsv object
• nn.rgb2hex() // converts r, g, b values to a hex color string
• nn.rgb2hsl() // converts r, g, b values to an hsl object
• nn.rgb2hsv() // converts r, g, b values to an hsv object
• nn.hsl2hex() // converts h, s, l values to a hex color string
• nn.hsl2rgb() // converts h, s, l values to an rgb object
• nn.hsl2hsv() // converts h, s, l values to an hsv object
• nn.hsv2hex() // converts h, s, v values to a hex color string
• nn.hsv2rgb() // converts h, s, v values to an rgb object
• nn.hsv2hsl() // converts h, s, v values to an hsl object

classes

• nn.FileUploader This comes from the FileUploader.js sub-module.

contributions

If you'd like to contribute to this repository, our contributors doc include steps you should take to setup a local project as well as contribute any bug fixes, additions or other changes.