Zomia Node.js API

Image Processing & Face Detection

The API enables image manipulation via options passed on the URL. Here's a pair of original, unprocessed images:

The following options may be passed in the URL after https://api.zom.io/v1/Images/S3/ as comma-delimited pairs (e.g., w_400,d_loose):

1. w: {option: 'width', type: 'int', min: 10, max: 4000}
2. h: {option: 'height', type: 'int', min: 10, max: 4000}
3. f: {option: 'fit', type: 'string', accept: 'cover|contain|fill|inside|outside'} // For resizing, see https://sharp.pixelplumbing.com/api-resize
4. g: {option: 'gravity', type: 'string'} // For cropping, see https://sharp.pixelplumbing.com/api-resize/#crop
5. q: {option: 'quality', type: 'int', min: 1, max: 100} // JPEG/PNG/TIFF compression
6. r: {option: 'rotate', type: 'int', min: 90, max: 270, accept: '90|180|270'}
7. d: {option: 'faceDetection', type: 'string', accept:'tight|loose'} // Do we do any face detection on crop?
8. e: {option: 'effects', type: 'array', accept: 'greyscale|flip|flop|contrasty'}
9. b: {option: 'badge', type: 'string', accept: 'a|cap|trophy|dollar|pay|cap|star|star_multi'}
10. c: {option: 'ribbonColor', type: 'string', accept: 'pink|blue|grayscale|round'}
11. l: {option: 'badgeLocation', type: 'string', accept: 'right|left'}
12. o: {option: 'apiOperation', type: 'string', accept: "process|round|square|portrait|portrait_round"}

Examples of face detection and other manipulation performed on the unprocessed/uncropped images above (no CSS applied):

Image Generator: E-mail Message Banners

The API enables generation of images for usage in Zomia's custom e-mail message/e-card template. Examples:

To customize e-mail banners, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/EmailBanner/{PATH} URL, where {PATH} consists of name/value pairs:

1. Title - enter as name/value pair on the URL, e.g., "/Title/Grade%20Report/"
2. Subtitle - enter as name/value pair, e.g., "/Subtitle/January%202018/"
3. TextAlign (title/subtitle alignment) - enter as name/value pair where value is one of "left|center|right" (defaults center), e.g., "/TextAlign/right/"
4. Color - enter a valid hexadecimal color value (defaults to Zomia blue), e.g., "/Color/333333/"
5. *BaseUrl - This value MUST BE PRESENT AS THE LAST URL PARAMETER (last because the URL value will have any number of "/" characters present); this is the path to the base banner photo, e.g., /BaseUrl/https://cdn.zomia.org/images/banners/individuals/2017-09-23_5-000684_1728x864.jpg"

Image Generator: Loan MAP Schedules

Zomia's MAP schedules can also be generated dynamically via the API. Seen below are examples for both versions of Zomia's MAP:

To customize MAP schedules, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/MapSchedule/{PATH} URL, where {PATH} consists of name/value pairs:

1. *LoanAmount - valid values range from 500 to 30,000, e.g., "/LoanAmount/13000/"
2. *IndividualId - enter any student IndividualId to generate a MAP for that student, e.g., "/IndividualId/300001/" – note that the MAP version will be determined automatically based upon the student's loan contract
3. MapVersion - enter 1 (pre-2018 MAP model) or 2 (2018 model) or 3 (2019 model), e.g., "/MapVersion/1/"; if no MapVersion is entered, the current model (version 3, 2019) is used

* Either LoanAmount or IndividualId must be specified, but not both at once.

Image Generator: Student Pie Charts

Produce pie charts based upon student data - must pass IndividualId, LoanId, or Percentage (0-100) and Mode, e.g., /Images/Generator/Pie/IndividualId/300001/Mode/Repaid

To customize pies, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/Pie/{PATH} URL, where {PATH} consists of name/value pairs:

1. *Mode - one of Funded or Repaid, if anything else (e.g., "Filled"), a Percentage option must be specified
2. Percentage - 0 to 100, manually set percentage displayed in pie chart - required if Mode is not Funded or Repaid
3. Color - six-digit HEX, no #
4. Background - six-digit HEX, no #, background-color upon which pie is rendered
5. OmitText - 1/true to skip generation of the percentage text overlay
6. TextPercentageOnly - 1/true to display only the percentage as the text overlay
7. Width - number, in pixels
8. Height - number, in pixels
9. Donut - 1|0, set to 1 to render a donut
10. DonutColor - six-digit HEX, no #
11. TextColor - six-digit HEX, no #
12. Format - jpg|png|JPG|PNG
13. Quality - 1 to 100, with 100 being best, generally only affects JPG output

Image Generator: Student Pie Portraits

Produce pie charts layered atop student portraits - must pass IndividualId, LoanId, or Percentage (0-100) and Mode, e.g., /Images/Generator/PiePortrait/IndividualId/300001/Mode/Repaid. Same options apply as Pie module above.

Image Generator: Individual/Organization Portraits & Thumbnails

Generate platform entity portraits and thumbnails. Follows similar pattern used with PiePortrait above, although EntityId, OrganizationId, or IndividualId may be passed to designate the entity. Examples:

To customize portraits and thumbnails, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/EntityId/XXXXXX/Portrait/{PATH} or .../Thumbnail/{PATH} URL, where {PATH} consists of name/value pairs:

1. Width - number, in pixels
2. Height - number, in pixels
3. Sharpen - number between 1 and 10 for sharpening level (useful for tiny thumbnail generation)